🩺 Audit fixes: CLI contracts, config safety, CI consolidation, docs & release status#4
Merged
Conversation
mac setup --help / -h previously failed with "Unknown option" because the command wrapper did not recognise the help flags, while scripts/setup.sh --help worked. Add the missing case so the CLI contract is consistent, and cover it in the smoke tests. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
mac doctor ignored all arguments, so mac doctor --help actually ran the full diagnostic (including brew doctor) instead of printing usage. Parse arguments and expose a read-only --help/-h flag, rejecting unknown options. Covered by the CLI smoke tests. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
mac doctor printed "brew missing" or "mac CLI missing" but always ended with "Doctor done" and exit 0, which is misleading for CI and automation. Track required-tool failures and return a non-zero status while keeping brew warnings non-fatal. A stubbed-PATH smoke test covers the failure path. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
scripts/setup.sh created ./logs/setup.log relative to the current directory, so running "mac setup" from another project polluted that project with a logs/ folder. Write to a user-level location ($HOME/Library/Logs/mac-dev-setup by default, overridable via MAC_DEV_SETUP_LOG_DIR) and assert the absence of CWD pollution in tests. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
git.sh wrote init.defaultBranch directly into the global git config, outside the managed include.path. The same setting already lives in configs/git/.gitconfig, so the direct write was both redundant and an intrusive change to the user's global config. Drop it and let the include be the single source of truth. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
zsh.sh regenerated configs/zsh/completions/_mac on every "mac setup", mutating a versioned file inside the installed checkout (which breaks on read-only or otherwise pinned installs). The completion is already generated and committed during development and verified up to date in CI, so setup now installs the committed file as-is. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The README documents seven MacDevSetup-managed files, but --remove-config only handled the git include, alias.sh and the zsh completion. Extend remove_config to the managed zsh dotfiles (.zprofile, .zshrc, .zsh_plugins.txt, .p10k.zsh) using the existing remove_if_identical guard, so files are removed only when they match the versioned copy and left untouched (with a warning) otherwise. Covered by a dry-run smoke test against a temporary HOME. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
profile_list discovers profiles by scanning profiles/, but profile_name_is_valid hard-coded "full|minimal", so any newly added profile directory was listed yet rejected by validation. Validate names against a safe charset (which also prevents path traversal) and let profile_exists decide availability. Usage strings now use a generic <profile> placeholder alongside the dynamic profile list. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
scripts/check-commit.sh hard-coded only five gitmoji and checked just the last commit, so it diverged from the commitlint config used by the local commit-msg hook and the Makefile, and would have rejected valid history (emoji such as the refactor/bump gitmoji, including Dependabot's prefix). Replace it with commitlint over the full PR/push range, reusing the same shared config as the local hook, and drop the redundant script. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Three macOS workflows overlapped: brewfile.yml installed the full profile and ran hardening twice (once via verify.sh, once directly), hardening.yml ran hardening a third time, and ci-macos.yml installed the full profile again. All three also triggered on every branch push. Collapse them into one macOS workflow that caches Homebrew, installs the full profile, applies setup once, and runs verify.sh (which already runs the hardening layer). Trigger only on pull_request and pushes to main to stop burning macOS minutes on every feature-branch push. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
hardening.sh grepped the machine's global `brew list`, so any developer machine that legitimately had one of the denied tools (e.g. direnv) would fail the gate. Scan the declared profile Brewfiles instead — the contract this repository actually owns — document the rationale, and fold the orbctl check (previously duplicated in verify.sh) into the single denylist. Brew doctor/outdated stay informational and only run when brew is available. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The post-install check ran `exit 1` if the mac completion was not already registered in a freshly spawned shell. On customised shells, or before compinit has picked up ~/.zsh/completions, this made an otherwise successful "mac setup" report failure. Downgrade it to a warning; the completion loads in a new shell session. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Tool docs told readers to add/remove entries "in/from the root Brewfile", but the root Brewfile is only a compatibility symlink; the editable source is profiles/full/Brewfile (as homebrew.md and the architecture docs already state). Update the boilerplate across the tool docs to reference the real source, leaving the legitimate descriptions of the compatibility symlink untouched. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add a guard that fails the quality job if known local artifacts (.DS_Store, a logs/ directory, or *.log files) are ever tracked. These are gitignored today, but the check makes the boundary explicit so a forced add cannot slip generated state into the repository. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
commitlint.config.cjs requires @gitmoji/gitmoji-regex directly, but it was only present as a transitive dependency of commitlint-config-gitmoji, so a dedupe or upstream change could break commit linting. Declare it explicitly in devDependencies. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The package declared 1.0.0 and the changelog had a dated 1.0.0 section, but no v1.0.0 tag exists (tags stop at v0.4.1) and the entire modular mac CLI is in fact unreleased; the old "1.0.0" entry actually described the 0.2.0 work. Move the package to 0.5.0, rebuild the changelog honestly (Unreleased holds the CLI and audit fixes; fill in the missing 0.2.0 and 0.4.1 sections from history), and uncheck the 1.0.0 version criteria that are no longer true so they read as targets again. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Every tool page repeated the same generic "brew bundle --file=Brewfile" install block and a per-tool "Updates" section that only ran "brew upgrade <tool>", both already documented canonically in docs/homebrew/homebrew.md. Replace the generic install block with a pointer to the Homebrew setup doc and drop the boilerplate Updates sections, while preserving tool-specific content (direct install, verify commands, and data-safety notes such as OrbStack's runtime checks). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Labault
added a commit
that referenced
this pull request
Jun 18, 2026
🩺 Audit fixes: CLI contracts, config safety, CI consolidation, docs & release status
Labault
added a commit
that referenced
this pull request
Jun 21, 2026
🩺 Audit fixes: CLI contracts, config safety, CI consolidation, docs & release status
Labault
added a commit
that referenced
this pull request
Jun 22, 2026
🩺 Audit fixes: CLI contracts, config safety, CI consolidation, docs & release status
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Independent senior-level audit of the repository, implemented as atomic commits (gitmoji + conventional commits). Each change ships with tests and/or CI guards;
npm test,pre-commit run --all-filesandcommitlintpass across the whole branch.P0 — CLI contracts & side effects
mac setup --help/mac doctor --helpnow print usage instead of erroring / silently running diagnostics.mac doctorexits non-zero when a required tool is missing (CI/automation friendly).mac setupwrites its log to~/Library/Logs/mac-dev-setupinstead of polluting the current directory.P1 — Config / uninstall / profiles
init.defaultBranchnow comes solely from the managed include (no intrusive global write).uninstall --remove-configcovers all 7 managed files (was 3), using the existing identical-only guard.full|minimal); safe-charset check prevents path traversal.P2 — CI & commit quality
commitlintover the PR/push range (drops the divergentcheck-commit.shthat broke Dependabot's⬆️prefix and existing🚀/♻️history).main.brew list), with theorbctlcheck folded in.P3 — Version / docs
profiles/full/Brewfile..DS_Store,logs/,*.log).@gitmoji/gitmoji-regexdeclared as a direct dependency.0.5.0): the entiremacCLI was actually unreleased (tags stop atv0.4.1), and the old changelog "1.0.0" entry really described0.2.0. Changelog rebuilt honestly with the missing0.2.0/0.4.1sections; 1.0.0 criteria re-opened as targets.F2 — Documentation deduplication
brew bundleinstall block and boilerplate per-toolUpdatessections from 19 tool docs, pointing to the canonicaldocs/homebrew/homebrew.mdwhile keeping tool-specific content (−175 lines net).