🎯 v1.0.0 readiness: exit-status fix, shellcheck, bats suite, manual release, extra commands

.github/workflows/ci-macos.yml

@@ -14,6 +14,19 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
 
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Install Node dependencies
+        env:
+          HUSKY: "0"
+        run: npm ci
+
+      - name: Run test suite
+        run: npm test
+
       - name: Cache Homebrew
         uses: actions/cache@v4
         with:

.github/workflows/ci.yml

@@ -80,6 +80,9 @@ jobs:
           HUSKY: "0"
         run: npm ci
 
+      - name: Run test suite
+        run: npm test
+
       - name: Lint commit messages
         env:
           PR_BASE_SHA: ${{ github.event.pull_request.base.sha }}
@@ -113,8 +116,3 @@ jobs:
 
       - name: Run repository quality checks
         run: pre-commit run --all-files --show-diff-on-failure
-
-      - name: Verify generated Zsh completion
-        run: |
-          bash scripts/generate-zsh-completion.sh
-          git diff --exit-code -- configs/zsh/completions/_mac

.pre-commit-config.yaml

@@ -14,6 +14,13 @@ repos:
     hooks:
       - id: gitleaks
 
+  - repo: https://github.com/shellcheck-py/shellcheck-py
+    rev: v0.10.0.1
+    hooks:
+      - id: shellcheck
+        args: [-x]
+        files: ^(scripts/.*\.sh|install\.sh)$
+
   - repo: local
     hooks:
       - id: markdownlint-cli2

.shellcheckrc

@@ -0,0 +1,2 @@
+# Allow `# shellcheck source=...` directives to resolve sourced libraries.
+external-sources=true

CHANGELOG.md

@@ -25,7 +25,10 @@ The format is inspired by Keep a Changelog, and the project follows semantic ver
 - Generated Zsh completion for `mac`, built from the command registry and
   verified in CI.
 - Structured logging helpers and unified error handling across the CLI.
-- CLI smoke tests (`npm test`) and commit linting through commitlint.
+- Opt-in `mac defaults`, `mac keyboard` and `mac vscode` commands wrapping the
+  macOS defaults, keyboard layout and VS Code extension scripts.
+- A bats test suite covering the libraries, CLI, update and install flows, run
+  via `npm test` in CI.
 
 ### Changed
 
@@ -35,16 +38,23 @@ The format is inspired by Keep a Changelog, and the project follows semantic ver
   writes to the global config.
 - macOS CI consolidated into a single gate, and commits are linted with
   commitlint across the pull request range.
+- Shell scripts are linted with shellcheck in CI.
+- VS Code extensions are no longer declared in the Brewfile (which made the
+  macOS CI depend on the flaky extension marketplace); install them with
+  `mac vscode`, the single source of truth being the configs/vscode lists.
 - `mac setup` writes its log to a user-level location instead of the current
   working directory.
+- Releases are performed manually following the documented process; the
+  unreliable release-please workflow was removed.
 
 ### Fixed
 
 - `mac setup --help` and `mac doctor --help` print usage instead of failing or
   silently running diagnostics.
 - `mac doctor` exits non-zero when a required tool is missing.
-- Setup no longer regenerates the versioned completion file and no longer fails
-  when completion is not yet active in the current shell.
+- Setup no longer regenerates the versioned completion file, no longer fails
+  when completion is not yet active in the current shell, and reports a reliable
+  exit status.
 
 ## 0.4.1 - 2026-06-17
 

README.md

@@ -65,9 +65,9 @@ Setup:
 maintenance.
 
 `full` installs the complete curated developer environment, including language
-tooling, quality tools, GUI applications, VS Code extensions, and
-container/database utilities. The root `Brewfile` is a compatibility link to
-`profiles/full/Brewfile`.
+tooling, quality tools, GUI applications, and container/database utilities. The
+root `Brewfile` is a compatibility link to `profiles/full/Brewfile`. VS Code
+extensions are managed separately and installed with `mac vscode`.
 
 ## CLI Usage
 
@@ -120,6 +120,17 @@ Remove the installed checkout when it matches `~/.mac-dev-setup`:
 mac uninstall --remove-install-dir
 ```
 
+### Optional commands
+
+These commands apply opt-in changes and are not run by `mac setup`:
+
+```bash
+mac defaults   # apply curated macOS Finder/Dock/keyboard defaults
+mac keyboard   # install the Francais OSS Mac keyboard layout
+mac vscode     # install the curated VS Code extensions
+mac vscode --with-optional
+```
+
 ## Managed Files
 
 MacDevSetup may manage these user-level files:

configs/zsh/completions/_mac

@@ -7,10 +7,13 @@ _mac() {
 
   commands=(
     'help:List available commands.'
+    'defaults:Apply the curated macOS system defaults.'
     'doctor:Run system diagnostics for the macOS development setup.'
+    'keyboard:Install the French OSS keyboard layout.'
     'setup:Install and configure the macOS development setup.'
     'uninstall:Remove the mac CLI symlink and managed shell PATH entry.'
     'update:Update the mac CLI from its git repository.'
+    'vscode:Install the curated VS Code extensions.'
   )
 
   if (( CURRENT == 2 )); then

docs/keyboard/french-oss.md

@@ -52,7 +52,13 @@ The layout contains adaptations for the internal Apple keyboard, including corre
 
 ## Installation
 
-Install the layout with:
+Install the layout with the CLI:
+
+~~~bash
+mac keyboard
+~~~
+
+Or run the script directly:
 
 ~~~bash
 ./scripts/install-keyboard-layout.sh

docs/macos/macos-defaults.md

@@ -73,7 +73,13 @@ Validate it with ShellCheck:
 shellcheck scripts/apply-macos-defaults.sh
 ~~~
 
-Apply the configuration:
+Apply the configuration with the CLI:
+
+~~~bash
+mac defaults
+~~~
+
+Or run the script directly:
 
 ~~~bash
 ./scripts/apply-macos-defaults.sh

docs/releases/release-process.md

@@ -4,6 +4,11 @@ This document describes the release workflow for Mac Dev Setup.
 
 The project uses semantic versioning where applicable and maintains notable changes in the root `CHANGELOG.md` file.
 
+Releases are performed **manually** by following the steps below. There is no
+automated release bot: the repository's gitmoji-first commit convention does not
+map cleanly onto conventional-commit release automation, so the changelog,
+version bump, tag, and GitHub release are prepared by a maintainer.
+
 ## Release preparation
 
 Before starting a release:

docs/releases/v1.0.0.md

@@ -52,7 +52,7 @@ uninstall flows, and quality checks suitable for ongoing maintenance.
 - [x] Repository quality validation is configured in GitHub Actions.
 - [x] Homebrew validation is configured in GitHub Actions.
 - [x] macOS validation is configured in GitHub Actions.
-- [x] Release Please automation is configured for future releases.
+- [x] The release process is documented and performed manually (see release-process.md).
 - [x] Dependabot monitors GitHub Actions dependencies.
 
 ## Documentation

docs/vscode/vscode.md

@@ -54,13 +54,19 @@ They cover the main PHP and Symfony development workflow:
 - DotEnv syntax support
 - YAML validation and completion
 
-Install them with:
+Install them with the CLI:
+
+~~~bash
+mac vscode
+~~~
+
+Or run the script directly:
 
 ~~~bash
 ./scripts/install-vscode-extensions.sh
 ~~~
 
-The script is idempotent and skips extensions that are already installed.
+The command is idempotent and skips extensions that are already installed.
 
 ## Optional extensions
 
@@ -74,6 +80,12 @@ They include personal, visual, AI-assisted, and specialized workflow extensions.
 
 Install both recommended and optional extensions with:
 
+~~~bash
+mac vscode --with-optional
+~~~
+
+Or run the script directly:
+
 ~~~bash
 ./scripts/install-vscode-extensions.sh --with-optional
 ~~~

package.json

@@ -7,7 +7,7 @@
     "doc": "docs"
   },
   "scripts": {
-    "test": "bash scripts/test-cli.sh",
+    "test": "bats tests",
     "prepare": "husky"
   },
   "repository": {
@@ -26,6 +26,7 @@
     "@commitlint/cli": "^21.0.2",
     "@commitlint/config-conventional": "^21.0.2",
     "@gitmoji/gitmoji-regex": "^1.0.0",
+    "bats": "^1.13.0",
     "commitlint-config-gitmoji": "^2.3.1",
     "husky": "^9.1.7"
   }

profiles/full/Brewfile

@@ -97,24 +97,6 @@ cask "visual-studio-code"
 # Rust-based terminal
 cask "warp"
 
-# Editor extensions
-
-vscode "anthropic.claude-code"
-vscode "avaly.restore-git-branch-tabs-improved"
-vscode "bmewburn.vscode-intelephense-client"
-vscode "christian-kohler.path-intellisense"
-vscode "eamodio.gitlens"
-vscode "github.vscode-github-actions"
-vscode "hogashi.crontab-syntax-highlight"
-vscode "mechatroner.rainbow-csv"
-vscode "mehedidracula.php-namespace-resolver"
-vscode "mikestead.dotenv"
-vscode "monokai.theme-monokai-pro-vscode"
-vscode "redhat.vscode-yaml"
-vscode "sanderronde.phpstan-vscode"
-vscode "whatwedo.twig"
-vscode "xdebug.php-debug"
-
 # Runtime-managed tools
 
 uv "claude-monitor"

scripts/commands/defaults.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+# Description: Apply the curated macOS system defaults.
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+# shellcheck source=scripts/lib/logging.sh
+source "$REPO_DIR/scripts/lib/logging.sh"
+
+print_usage() {
+  log_line "Usage: mac defaults [--help]"
+  log_line ""
+  log_line "Apply the curated Finder, Dock, screenshot, and keyboard defaults."
+}
+
+main() {
+  case "${1:-}" in
+    "") ;;
+    --help | -h)
+      print_usage
+      exit 0
+      ;;
+    *)
+      error "Unknown option: $1"
+      print_usage >&2
+      exit 1
+      ;;
+  esac
+
+  exec bash "$REPO_DIR/scripts/apply-macos-defaults.sh"
+}
+
+main "$@"

scripts/commands/keyboard.sh

@@ -0,0 +1,36 @@
+#!/bin/bash
+# Description: Install the French OSS keyboard layout.
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+# shellcheck source=scripts/lib/logging.sh
+source "$REPO_DIR/scripts/lib/logging.sh"
+
+print_usage() {
+  log_line "Usage: mac keyboard [--help]"
+  log_line ""
+  log_line "Install the bundled Francais OSS Mac keyboard layout. Log out and"
+  log_line "back in, then enable it in macOS Input Sources."
+}
+
+main() {
+  case "${1:-}" in
+    "") ;;
+    --help | -h)
+      print_usage
+      exit 0
+      ;;
+    *)
+      error "Unknown option: $1"
+      print_usage >&2
+      exit 1
+      ;;
+  esac
+
+  exec bash "$REPO_DIR/scripts/install-keyboard-layout.sh"
+}
+
+main "$@"