diff --git a/.github/workflows/scorecard.yml b/.github/workflows/scorecard.yml index 9d0e23d..c53d959 100644 --- a/.github/workflows/scorecard.yml +++ b/.github/workflows/scorecard.yml @@ -5,7 +5,7 @@ on: schedule: - cron: '30 1 * * 1' # Every Monday at 01:30 UTC push: - branches: [main] + branches: [main, develop] workflow_dispatch: permissions: read-all @@ -29,8 +29,8 @@ jobs: with: results_file: results.sarif results_format: sarif - # Only publish to scorecard.dev from main — the action enforces this - publish_results: ${{ github.ref == 'refs/heads/main' }} + # Publish to scorecard.dev only from the default branch. + publish_results: ${{ github.ref_name == github.event.repository.default_branch }} - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 with: @@ -39,7 +39,7 @@ jobs: retention-days: 5 - uses: github/codeql-action/upload-sarif@e46ed2cbd01164d986452f91f178727624ae40d7 # v4 - if: github.ref == 'refs/heads/main' + if: github.ref_name == github.event.repository.default_branch continue-on-error: true with: sarif_file: results.sarif diff --git a/CHANGELOG.md b/CHANGELOG.md index 74b0a30..e3e7066 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -22,12 +22,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [1.0.0] - 2026-03-29 ### Added -- Bootstrap script (`setup.sh`) — zero-to-productive on a fresh Mac in one command +- Bootstrap script (`setup.sh`). Zero-to-productive on a fresh Mac in one command - Homebrew tap with `dev-tools` formula (`Formula/dev-tools.rb`) -- `Brewfile` — full package list: CLI tools, languages, cloud/devops, GUI casks -- `Brewfile.ci` — CLI-only subset for fast CI runs +- `Brewfile`. Full package list: CLI tools, languages, cloud/devops, GUI casks +- `Brewfile.ci`. CLI-only subset for fast CI runs - Dotfiles: `zshrc`, `vimrc` (vim-plug + ALE + vim-go + gruvbox), `secrets.template` - Scripts: `install-dotfiles.sh`, `setup-credentials.sh`, `setup-mcps.sh`, `upgrade.sh` -- `CLAUDE.md` — Claude Code preferences and learned preferences system +- `CLAUDE.md`. Claude Code preferences and learned preferences system - CI/CD: lint (`shellcheck`), formula audit (`brew audit --strict`), integration test (macOS runner) - Release pipeline with validation gate on `v*.*.*` tags diff --git a/CLAUDE.md b/CLAUDE.md index 560d99d..3f512c3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,4 +1,4 @@ -# CLAUDE.md — mac-dev-setup +# CLAUDE.md. Mac-dev-setup This file is read by Claude Code at the start of every session in this repo. It captures developer preferences, project conventions, and accumulated knowledge. @@ -8,16 +8,16 @@ It captures developer preferences, project conventions, and accumulated knowledg ## About This Repo This is a personal macOS developer environment managed as a Homebrew tap. -The goal is a single command that gets a machine from zero to fully productive — -tools, dotfiles, credentials, MCPs, and Claude Code configuration all included. +The goal is a single command that gets a machine from zero to fully productive, +with tools, dotfiles, credentials, MCPs, and Claude Code configuration all included. **Key files:** -- `setup.sh` — bootstrap entry point (run on a fresh machine) -- `Brewfile` — full package list including GUI casks -- `Brewfile.ci` — CLI-only subset used in CI (no heavy casks) -- `Formula/dev-tools.rb` — Homebrew formula for the tap -- `dotfiles/` — zshrc, vimrc, secrets.template (symlinked into $HOME) -- `scripts/` — install-dotfiles, setup-credentials, setup-mcps, upgrade +- `setup.sh`. Bootstrap entry point (run on a fresh machine) +- `Brewfile`. Full package list including GUI casks +- `Brewfile.ci`. CLI-only subset used in CI (no heavy casks) +- `Formula/dev-tools.rb`. Homebrew formula for the tap +- `dotfiles/`. Zshrc, vimrc, secrets.template (symlinked into $HOME) +- `scripts/`. Install-dotfiles, setup-credentials, setup-mcps, upgrade --- @@ -30,17 +30,17 @@ tools, dotfiles, credentials, MCPs, and Claude Code configuration all included. ### Shell - Shell: **zsh** -- Prompt is minimal (`%n:%1~ $ `) — no heavy frameworks like oh-my-zsh +- Prompt is minimal (`%n:%1~ $ `). No heavy frameworks like oh-my-zsh - Aliases and functions live in `dotfiles/zshrc`, not scattered elsewhere ### Languages -- **Go** — preferred for backend services and CLI tools -- **Python** — scripting, data work, AI integrations -- **Java** — enterprise/existing projects (Maven) -- **Node/TypeScript** — frontend and MCP server work +- **Go**. Preferred for backend services and CLI tools +- **Python**. Scripting, data work, AI integrations +- **Java**. Enterprise/existing projects (Maven) +- **Node/TypeScript**. Frontend and MCP server work ### Cloud & Infrastructure -- **OCI (Oracle Cloud)** and **DigitalOcean** — both actively used +- **OCI (Oracle Cloud)** and **DigitalOcean**. Both actively used - **Kubernetes** locally via `kind`, remotely via OCI/DO clusters - **ArgoCD** for GitOps deployments - **Terraform** for infrastructure as code @@ -49,14 +49,14 @@ tools, dotfiles, credentials, MCPs, and Claude Code configuration all included. - **Branch model:** `main` = latest release (always stable). `develop` = integration branch. - Always branch from `develop`, never commit directly to `main` or `develop` - PRs always target `develop` -- `main` is only updated via CLI merge (`git merge --no-ff origin/develop`) by `/publish-release` — **never via a GitHub PR**. GitHub's merge button squash-merges by default, dropping ancestry and causing conflicts on the next release. +- `main` is only updated via CLI merge (`git merge --no-ff origin/develop`) by `/publish-release`. **never via a GitHub PR**. GitHub's merge button squash-merges by default, dropping ancestry and causing conflicts on the next release. - Always open a PR for review before merging -- Commit messages should be descriptive — explain *why*, not just *what* +- Commit messages should be descriptive. Explain *why*, not just *what* - Conventional commits style: `feat:`, `fix:`, `docs:`, `chore:` ### Scripting Standards - All shell scripts must pass `shellcheck` with no warnings -- Scripts should be idempotent — safe to run multiple times +- Scripts should be idempotent. Safe to run multiple times - Always use `set -euo pipefail` at the top of bash scripts - Prefer explicit error messages over silent failures @@ -67,7 +67,7 @@ tools, dotfiles, credentials, MCPs, and Claude Code configuration all included. act pull_request -j lint # lint job only act pull_request -j formula-audit # formula audit only ``` -- `Brewfile.ci` exists for fast CI runs — add new CLI tools there too +- `Brewfile.ci` exists for fast CI runs. Add new CLI tools there too - See `TESTING.md` for full acceptance testing options ### Secrets & Credentials @@ -118,11 +118,11 @@ See `VERSIONING.md` for the full versioning scheme. > **How this section works:** As Claude works with you across sessions and notices > a consistent pattern or preference, it should suggest adding it here as a one-liner. -> You review, refine, and commit it. This keeps durable knowledge in the repo — +> You review, refine, and commit it. This keeps durable knowledge in the repo: > not session-specific questions, but things that should be true on a clean install. - Prefer interactive scripts with clear progress output (use `▶` prefix for steps, `✓` for success) - Prefer ASCII art / box-drawing separators (`━━━`) over plain `---` in terminal output -- Keep CI fast — integration test should complete under 5 minutes +- Keep CI fast. Integration test should complete under 5 minutes - GUI cask installs are always deferred to manual or `setup.sh`, never required in CI diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c6ce5e7..62c8caa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -13,11 +13,11 @@ It is published openly so others can learn from it, fork it, and adapt it for th - **PRs are welcome** for genuine bugs, broken tooling, or improvements that are broadly useful and not preference-specific. - **Preference PRs will generally be declined.** If you prefer a different shell, editor, color - scheme, or aliasing style — fork it. This repo is not a general-purpose tool; it is a specific + scheme, or aliasing style. Fork it. This repo is not a general-purpose tool; it is a specific person's environment. - **Alan has final say** on what goes into this repo. A PR may be well-written, well-tested, and genuinely useful, and still be declined because it doesn't fit how Alan works. That is not a - reflection of your contribution quality — it just isn't the right repo for it. + reflection of your contribution quality. It just isn't the right repo for it. If you are building your own environment, fork this repo and make it yours. If you've found something that is broken or outdated in a way that affects everyone, open a PR. @@ -27,9 +27,9 @@ If you've found something that is broken or outdated in a way that affects every ## Getting Started (for contributors) **Prerequisites:** -- [`shellcheck`](https://github.com/koalaman/shellcheck) — `brew install shellcheck` -- [`act`](https://github.com/nektos/act) — `brew install act` — local GitHub Actions runner -- [`tart`](https://github.com/cirruslabs/tart) — `brew install cirruslabs/cli/tart` — VM acceptance tests +- [`shellcheck`](https://github.com/koalaman/shellcheck). `brew install shellcheck` +- [`act`](https://github.com/nektos/act). `brew install act`. Local GitHub Actions runner +- [`tart`](https://github.com/cirruslabs/tart). `brew install cirruslabs/cli/tart`. VM acceptance tests Fork and clone to the standard path: ```bash @@ -70,10 +70,10 @@ that is not a GUI cask must also appear in `Brewfile.ci`. ## Adding a Tool -1. **Brewfile** — add the formula. If it is a CLI tool, add it to `Brewfile.ci` as well. -2. **Dotfiles** — add relevant aliases or configuration to `dotfiles/zshrc`. -3. **Validate smoke test** — add `command -v ` to the smoke-test step in `.github/workflows/validate.yml`. -4. **README table** — add a row to the appropriate table in `README.md`. +1. **Brewfile**. Add the formula. If it is a CLI tool, add it to `Brewfile.ci` as well. +2. **Dotfiles**. Add relevant aliases or configuration to `dotfiles/zshrc`. +3. **Validate smoke test**. Add `command -v ` to the smoke-test step in `.github/workflows/validate.yml`. +4. **README table**. Add a row to the appropriate table in `README.md`. --- diff --git a/README.md b/README.md index d82f6db..5b385d6 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ # mac-dev-setup -**An agentic-forward macOS developer environment — from zero to productive in one command.** +**An agentic-forward macOS developer environment. From zero to productive in one command.** [![Validate](https://github.com/amcheste/mac-dev-setup/actions/workflows/validate.yml/badge.svg)](https://github.com/amcheste/mac-dev-setup/actions/workflows/validate.yml) [![Version](https://img.shields.io/github/v/tag/amcheste/mac-dev-setup?label=version&sort=semver&color=0B0B0C)](https://github.com/amcheste/mac-dev-setup/releases) @@ -16,7 +16,7 @@ --- -Setting up a new Mac — or recovering from a disaster — should take minutes, not days. +Setting up a new Mac. Or recovering from a disaster. Should take minutes, not days. This repo automates everything: Homebrew packages, GUI apps, dotfiles, Vim plugins, credentials, and a fully configured [Claude Code](https://claude.ai/claude-code) environment with MCP servers wired in from day one. ```bash @@ -28,27 +28,27 @@ bash ~/Repos/amcheste/mac-dev-setup/setup.sh --- -## Agentic Development — Built In +## Agentic Development. Built In -This isn't just a tool installer. It sets up **Claude Code** as a first-class part of the development workflow — configured to know how you work, what you build, and how you prefer to do it. +This isn't just a tool installer. It sets up **Claude Code** as a first-class part of the development workflow. Configured to know how you work, what you build, and how you prefer to do it. ### Claude Code Configuration A `CLAUDE.md` file in this repo captures your development preferences so Claude Code understands your environment from the first session on any machine: -- **Tooling** — Vim, Zsh, Go/Python/Java/Node, OCI + DigitalOcean, Kubernetes via `kind` -- **Git workflow** — always branch, always PR, conventional commits, descriptive messages -- **Shell standards** — `shellcheck`-clean scripts, `set -euo pipefail`, idempotent installs -- **Project conventions** — how to test with `act`, when to update `Brewfile.ci`, how to add tools +- **Tooling**. Vim, Zsh, Go/Python/Java/Node, OCI + DigitalOcean, Kubernetes via `kind` +- **Git workflow**. Always branch, always PR, conventional commits, descriptive messages +- **Shell standards**. `shellcheck`-clean scripts, `set -euo pipefail`, idempotent installs +- **Project conventions**. How to test with `act`, when to update `Brewfile.ci`, how to add tools -### Learned Preferences — A Model That Grows With You +### Learned Preferences. A Model That Grows With You The `CLAUDE.md` has a **Learned Preferences** section that acts as a living record of how you work. -As Claude Code works with you across sessions and notices consistent patterns — how you structure commits, which shortcuts you reach for, what output format you prefer — those observations get added back here and committed. Not session-specific questions, but durable preferences that should be true on every clean install. +As Claude Code works with you across sessions and notices consistent patterns. How you structure commits, which shortcuts you reach for, what output format you prefer. Those observations get added back here and committed. Not session-specific questions, but durable preferences that should be true on every clean install. -Over time, this file becomes a precise picture of your development style. New machine, new team member, new context — Claude Code picks it all up instantly. +Over time, this file becomes a precise picture of your development style. New machine, new team member, new context. Claude Code picks it all up instantly. -### MCP Servers — Claude Wired Into Your Stack +### MCP Servers. Claude Wired Into Your Stack `setup.sh` automatically configures [MCP servers](https://modelcontextprotocol.io) so Claude Code has direct access to your development infrastructure: @@ -56,7 +56,7 @@ Over time, this file becomes a precise picture of your development style. New ma |-----|--------------------| | **GitHub** | Read/write PRs, issues, Actions runs, code search, releases | | **Filesystem** | Navigate `~/Repos`, `~/Documents`, `~/.claude` beyond the active project | -| **Memory** | Persist facts across sessions — supplements `CLAUDE.md` with dynamic context | +| **Memory** | Persist facts across sessions. Supplements `CLAUDE.md` with dynamic context. | | **PostgreSQL** | Query local and dev databases directly in conversation | To reconfigure MCPs: `bash scripts/setup-mcps.sh` @@ -70,26 +70,26 @@ To reconfigure MCPs: `bash scripts/setup-mcps.sh` | Tool | Version Management | |------|--------------------| | Go | Direct via Homebrew | -| Python | `pyenv` — switch versions per project | -| Node.js | `nvm` — switch versions per project | +| Python | `pyenv`, switch versions per project | +| Node.js | `nvm`, switch versions per project | | Java | OpenJDK + Maven | ### Cloud & Infrastructure | Tool | Purpose | |------|---------| -| `kubectl` + `kind` | Kubernetes — local clusters and remote | +| `kubectl` + `kind` | Kubernetes, local clusters and remote | | `helm` | Kubernetes package manager | | `terraform` | Infrastructure as code | | `oci-cli` | Oracle Cloud Platform | | `doctl` | DigitalOcean CLI | -| `gh` | GitHub CLI — PRs, releases, Actions | +| `gh` | GitHub CLI, PRs, releases, Actions | ### Developer Utilities | Tool | Why It's Here | |------|--------------| -| `fzf` | Fuzzy finder — wired into shell history and Vim | +| `fzf` | Fuzzy finder, wired into shell history and Vim | | `ripgrep` | 10x faster than grep, respects `.gitignore` | | `fd` | Faster `find` with sane defaults | | `bat` | `cat` with syntax highlighting and line numbers | @@ -111,7 +111,7 @@ To reconfigure MCPs: `bash scripts/setup-mcps.sh` ## Dotfiles -Shell and editor configs live in `dotfiles/` and are **symlinked** into `$HOME` — edits in this repo take effect immediately, and `git diff` always shows what's changed. +Shell and editor configs live in `dotfiles/` and are **symlinked** into `$HOME`. Edits in this repo take effect immediately, and `git diff` always shows what's changed. ``` dotfiles/ @@ -124,11 +124,11 @@ dotfiles/ The `vimrc` turns Vim into a proper IDE without an IDE's weight: -- **[vim-plug](https://github.com/junegunn/vim-plug)** — plugin manager, auto-bootstrapped -- **[ALE](https://github.com/dense-analysis/ale)** — async lint and fix on save (`goimports`, `black`, `tflint`) -- **[vim-go](https://github.com/fatih/vim-go)** — Go development (goimports, highlighting, `:GoBuild`) -- **[fzf.vim](https://github.com/junegunn/fzf.vim)** — fuzzy file/buffer/grep search (`f`, `r`) -- **[gruvbox](https://github.com/morhetz/gruvbox)** — colorscheme +- **[vim-plug](https://github.com/junegunn/vim-plug)**. Plugin manager, auto-bootstrapped +- **[ALE](https://github.com/dense-analysis/ale)**. Async lint and fix on save (`goimports`, `black`, `tflint`) +- **[vim-go](https://github.com/fatih/vim-go)**. Go development (goimports, highlighting, `:GoBuild`) +- **[fzf.vim](https://github.com/junegunn/fzf.vim)**. Fuzzy file/buffer/grep search (`f`, `r`) +- **[gruvbox](https://github.com/morhetz/gruvbox)**. Colorscheme - **[NERDTree](https://github.com/preservim/nerdtree)**, **[lightline](https://github.com/itchyny/lightline.vim)**, **[vim-fugitive](https://github.com/tpope/vim-fugitive)** - Filetype-aware indent: real tabs for Go, 2-space for YAML/Terraform/JSON, PEP8 for Python @@ -136,7 +136,7 @@ The `vimrc` turns Vim into a proper IDE without an IDE's weight: ## Secrets Management -Credentials live in `~/.secrets` — `chmod 600`, sourced by `.zshrc`, and **never committed**. +Credentials live in `~/.secrets`. `chmod 600`, sourced by `.zshrc`, and **never committed**. On first run, `setup.sh` launches an interactive wizard that populates it: @@ -196,7 +196,7 @@ Five automated workflows keep the environment reliable across every change and r | Workflow | Trigger | Purpose | |----------|---------|---------| | **Validate** | Every PR + push to `main` | Lint, shellcheck, formula audit, macOS integration test, commit lint + semver suggestion | -| **VM Acceptance** | Release tags + manual | Full install in a clean Tart VM — the release gate | +| **VM Acceptance** | Release tags + manual | Full install in a clean Tart VM, the release gate | | **Release** | `v*.*.*` tags | Validate → acceptance → publish release | | **Release Drafter** | PR open/update + push to `main` | Auto-labels PRs by type, drafts release notes | | **Label PR** | PR open/update | Adds content labels (`brew`, `scripts`, `dotfiles`, `ci`) | @@ -287,7 +287,7 @@ Push with `git push && git push --tags` to trigger the release pipeline. See **[ ## Testing -CI runs on every pull request against a real macOS runner. For full acceptance testing — including GUI casks and the interactive setup flow — see **[TESTING.md](TESTING.md)** for five options ranging from a local macOS user account to a UTM virtual machine. +CI runs on every pull request against a real macOS runner. For full acceptance testing. Including GUI casks and the interactive setup flow. See **[TESTING.md](TESTING.md)** for five options ranging from a local macOS user account to a UTM virtual machine. | Method | Covers Casks | Clean State | Effort | |--------|-------------|-------------|--------| @@ -311,9 +311,9 @@ Pairs with **Meslo LG Nerd Font** (installed automatically by the Brewfile). ## Contributing -This is Alan Chester's personal development environment. It is open for others to **fork and adapt** for their own use — that is the primary use case for anyone other than the owner. +This is Alan Chester's personal development environment. It is open for others to **fork and adapt** for their own use. That is the primary use case for anyone other than the owner. -Bug fixes and improvements that are genuinely broadly useful are welcome as pull requests. Preference-based changes will generally be declined — if the defaults don't fit your workflow, fork it and make it yours. +Bug fixes and improvements that are genuinely broadly useful are welcome as pull requests. Preference-based changes will generally be declined. If the defaults don't fit your workflow, fork it and make it yours. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full contribution guide, development workflow, and release process. @@ -323,4 +323,4 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for the full contribution guide, developm Released under the [MIT License](LICENSE). -You are free to use, fork, modify, and distribute this project for any purpose. No warranty is provided — this is a personal environment, not a supported product. +You are free to use, fork, modify, and distribute this project for any purpose. No warranty is provided. This is a personal environment, not a supported product. diff --git a/SECURITY.md b/SECURITY.md index 3932460..1d7219e 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -28,9 +28,9 @@ Security-relevant areas in this project: | Area | Concern | |------|---------| -| `dotfiles/secrets.template` | Must never contain real credentials — only placeholder slots | +| `dotfiles/secrets.template` | Must never contain real credentials, only placeholder slots | | `scripts/setup-credentials.sh` | Credential prompting and `~/.secrets` file handling | -| `setup.sh` | Bootstrap execution — runs with user privileges on a fresh machine | +| `setup.sh` | Bootstrap execution, runs with user privileges on a fresh machine | | `.github/workflows/` | CI/CD pipeline integrity and secret handling | ## Out of Scope diff --git a/TESTING.md b/TESTING.md index 91e3d17..27e178b 100644 --- a/TESTING.md +++ b/TESTING.md @@ -1,6 +1,6 @@ # Testing Guide -This document describes every layer of testing available for `mac-dev-setup` — +This document describes every layer of testing available for `mac-dev-setup`, from automated CI to full acceptance tests on a clean machine. --- @@ -9,7 +9,7 @@ from automated CI to full acceptance tests on a clean machine. Every pull request and push to `main` runs three jobs on GitHub Actions: -### Job 1 — Lint (Ubuntu, ~7 seconds) +### Job 1. Lint (Ubuntu, ~7 seconds) | Check | How | What it catches | |-------|-----|----------------| @@ -17,14 +17,14 @@ Every pull request and push to `main` runs three jobs on GitHub Actions: | Secret safety scan | Regex against `secrets.template` | Real credentials accidentally committed | | `.gitignore` verification | Grep for `.secrets` entry | Secrets file exposed in git | -### Job 2 — Formula Audit (macOS, ~30 seconds) +### Job 2. Formula Audit (macOS, ~30 seconds) | Check | How | What it catches | |-------|-----|----------------| | Formula correctness | `brew audit --strict` | Invalid formula structure, bad depends_on | | Formula style | `brew style` | Ordering violations, deprecated API usage | -### Job 3 — Integration Test (macOS, ~2 minutes, runs after Jobs 1 & 2) +### Job 3. Integration Test (macOS, ~2 minutes, runs after Jobs 1 & 2) | Check | How | What it catches | |-------|-----|----------------| @@ -36,8 +36,8 @@ Every pull request and push to `main` runs three jobs on GitHub Actions: | Tool availability | `command -v` for go, kubectl, helm, terraform, doctl, jq, gh | Package installs failing silently | **What CI does NOT cover:** -- GUI cask installs (Cursor, Docker Desktop, GoLand, etc.) — too slow for CI -- The full `Brewfile` — `Brewfile.ci` is a CLI-only subset +- GUI cask installs (Cursor, Docker Desktop, GoLand, etc.). Too slow for CI +- The full `Brewfile`. `Brewfile.ci` is a CLI-only subset - Interactive scripts (`setup-credentials.sh`, `setup-mcps.sh`) - Vim plugin installation - Homebrew bootstrap (runner already has Homebrew) @@ -47,7 +47,7 @@ These gaps are covered by the acceptance testing options below. --- -## Option 1 — Local Testing with `act` (Fastest) +## Option 1. Local Testing with `act` (Fastest) [`act`](https://github.com/nektos/act) runs GitHub Actions workflows locally using Docker. Use this to iterate on workflow changes without pushing. @@ -75,14 +75,14 @@ act pull_request --dryrun ``` **Notes:** -- `act` runs on Linux containers by default — the `lint` job works perfectly +- `act` runs on Linux containers by default. The `lint` job works perfectly - The `formula-audit` and `integration` jobs require macOS and will be skipped or emulated - Use `act` primarily for rapid iteration on the `lint` job before pushing -- First run downloads a Docker image (~1GB) — subsequent runs are fast +- First run downloads a Docker image (~1GB). Subsequent runs are fast --- -## Option 2 — New macOS User Account (Best Value) +## Option 2. New macOS User Account (Best Value) Create a second user on your Mac with a clean home directory. This is the closest thing to a real zero-state install without any additional hardware. @@ -118,7 +118,7 @@ This is the closest thing to a real zero-state install without any additional ha bash setup.sh ``` -4. Walk through the credential wizard — use dummy values or real ones. +4. Walk through the credential wizard. Use dummy values or real ones. 5. Verify the environment works as expected. @@ -135,9 +135,9 @@ Choose "Delete the home folder" to fully clean up. --- -## Option 3 — Manual GitHub Actions Run (Recorded & Reproducible) +## Option 3. Manual GitHub Actions Run (Recorded & Reproducible) -Add a `workflow_dispatch` trigger to run the full pipeline manually — including casks — from the GitHub UI. +Add a `workflow_dispatch` trigger to run the full pipeline manually. Including casks. From the GitHub UI. This gives you a cloud-hosted, recorded acceptance test you can run before any release. **To enable:** The `release.yml` workflow already has validation gates. @@ -171,10 +171,10 @@ A full run with casks takes ~30-45 minutes. Run manually before releases, not on --- -## Option 4 — UTM macOS Virtual Machine (Best Isolation) +## Option 4. UTM macOS Virtual Machine (Best Isolation) [UTM](https://mac.getutm.app) is a free, open-source VM manager for macOS. -A macOS guest VM gives true clean-room testing — snapshotable and restorable. +A macOS guest VM gives true clean-room testing. Snapshotable and restorable. **Install UTM:** ```bash @@ -187,7 +187,7 @@ brew install --cask utm 2. In UTM: New VM → Virtualize → macOS → select IPSW → configure RAM/disk (16GB RAM, 60GB disk recommended) -3. Complete macOS setup inside the VM — create a user account, skip Apple ID +3. Complete macOS setup inside the VM. Create a user account, skip Apple ID 4. Take a **snapshot** before running setup (UTM → VM menu → Snapshot → Save): ``` @@ -207,10 +207,10 @@ brew install --cask utm ``` **What this adds:** -- True clean-room — no pre-installed tools, fresh Homebrew -- Restorable — test as many times as you want from the same baseline -- Architecture testing — create ARM and Intel VMs to test both -- Offline testing — no cloud dependency +- True clean-room. No pre-installed tools, fresh Homebrew +- Restorable. Test as many times as you want from the same baseline +- Architecture testing. Create ARM and Intel VMs to test both +- Offline testing. No cloud dependency **Notes:** - Apple Silicon Macs can only run Apple Silicon macOS guests (not Intel macOS) @@ -219,19 +219,19 @@ brew install --cask utm --- -## Option 5 — Cloud Mac / GitHub Larger Runners (Team / Automated) +## Option 5. Cloud Mac / GitHub Larger Runners (Team / Automated) -For a fully automated, hosted clean-room test — relevant if this becomes a team setup. +For a fully automated, hosted clean-room test. Relevant if this becomes a team setup. **GitHub Larger Runners (macOS):** -- `macos-latest-xlarge` — Apple Silicon, 6 vCPU, 14GB RAM +- `macos-latest-xlarge`. Apple Silicon, 6 vCPU, 14GB RAM - Add to a workflow with `runs-on: macos-latest-xlarge` - Fully clean environment, billed per minute - Good for release gates on a team **MacStadium / Orka:** - Dedicated Mac hardware in the cloud -- Persistent VMs you control — snapshot, restore, automate +- Persistent VMs you control. Snapshot, restore, automate - Relevant when this setup is used across a team **Cost estimate for a full manual install run:** @@ -273,7 +273,7 @@ Use this checklist when running a full acceptance test (Options 2, 4, or 5): - [ ] `gh auth status` shows authenticated ### Shell Environment -- [ ] Open a new terminal — prompt appears correctly +- [ ] Open a new terminal. Prompt appears correctly - [ ] `repos` alias navigates to `~/Repos` - [ ] `k` alias works (`kubectl`) - [ ] `tf` alias works (`terraform`) @@ -281,4 +281,4 @@ Use this checklist when running a full acceptance test (Options 2, 4, or 5): ### Upgrade - [ ] `bash scripts/upgrade.sh` runs without errors on an already-configured machine -- [ ] Re-running `setup.sh` is idempotent — no duplicate installs or errors +- [ ] Re-running `setup.sh` is idempotent. No duplicate installs or errors diff --git a/VERSIONING.md b/VERSIONING.md index d7269c1..c200103 100644 --- a/VERSIONING.md +++ b/VERSIONING.md @@ -12,8 +12,8 @@ MAJOR.MINOR.PATCH[-PRE_RELEASE] | Component | When to increment | |-----------|-------------------| -| **MAJOR** | Breaking changes — tools removed, dotfiles restructured, setup flow changed in a non-backwards-compatible way | -| **MINOR** | New tools, new scripts, new MCP servers, new dotfile features — backwards compatible | +| **MAJOR** | Breaking changes: tools removed, dotfiles restructured, setup flow changed in a non-backwards-compatible way | +| **MINOR** | New tools, new scripts, new MCP servers, new dotfile features. Backwards compatible. | | **PATCH** | Bug fixes, documentation updates, CI improvements, dependency updates | | **PRE_RELEASE** | Optional suffix signalling a version is not yet mainstream stable (e.g. `-beta.1`, `-rc.2`) | @@ -23,10 +23,10 @@ MAJOR.MINOR.PATCH[-PRE_RELEASE] | Version range | Meaning | |---------------|---------| -| `0.x.x` | Pre-stable — actively being developed, breaking changes may occur between minor versions | -| `1.0.0`+ | Stable — the environment has been run on a real machine and proven reliable | -| `x.x.x-beta.N` | Beta — feature-complete for the version, but not yet fully tested | -| `x.x.x-rc.N` | Release candidate — final testing before a stable release | +| `0.x.x` | Pre-stable; actively being developed, breaking changes may occur between minor versions | +| `1.0.0`+ | Stable; the environment has been run on a real machine and proven reliable | +| `x.x.x-beta.N` | Beta; feature-complete for the version, but not yet fully tested | +| `x.x.x-rc.N` | Release candidate; final testing before a stable release | Pre-release versions are published to GitHub Releases with the **Pre-release** flag set, so they never show as the "latest" release. Only stable versions become the default install. @@ -35,7 +35,7 @@ so they never show as the "latest" release. Only stable versions become the defa ## Bumping a Version -Use the bump script — it updates `VERSION`, promotes `CHANGELOG.md`, commits, and tags: +Use the bump script. It updates `VERSION`, promotes `CHANGELOG.md`, commits, and tags: ```bash # Increment automatically @@ -72,7 +72,7 @@ tag push → validate (lint + formula audit + integration test) → publish Pre- tag push → validate → VM acceptance test (clean macOS VM) → publish Release ``` -Pre-release versions skip the VM acceptance gate by design — they are explicitly +Pre-release versions skip the VM acceptance gate by design. They are explicitly not fully vetted. The validate pipeline (shellcheck, formula audit, real macOS integration test) still runs and must pass for all release types.