Initial commit

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

macos/AGENTS.md

@@ -0,0 +1,90 @@
+# AGENTS.md
+
+## Project Overview
+
+This directory maintains a single shell script for initializing a newly set up
+macOS user account. Except for this file, do not split functionality into
+additional scripts, configuration generators, or other languages. Keep the
+script flat, easy to review, and directly executable on the target machine,
+in the same style as `../debian/debian13-init.sh`.
+
+## Scope
+
+This file applies to the `macos/` directory. The repository-level `AGENTS.md`
+still applies; where the two conflict, this file takes precedence.
+
+## Development Principles
+
+- Write Bash and use `#!/usr/bin/env bash` as the first line.
+- macOS ships bash 3.2 as `/bin/bash`. Do not use associative arrays,
+  `mapfile`, `${var,,}`, or other bash 4+ features.
+- Keep the script flat: a short comment followed by the commands it explains,
+  with no helper functions unless repetition clearly demands one.
+- Prefer `defaults write` for per-user preferences. Each write must be safe to
+  repeat. Use `-bool`, `-int`, or `-string` explicitly so the stored type is
+  stable.
+- Double-quote variables, and use `"${HOME}"` rather than `~` inside strings.
+- If a key only works on a specific macOS release, say so in a comment and
+  keep the version check in the script in sync.
+- Comments should explain reasons, compatibility constraints, or risks rather
+  than restating each line of code.
+
+## Security Requirements
+
+- Never store passwords, tokens, private keys, or other sensitive information
+  in the repository, command-line arguments, or logs.
+- Do not execute unverified remote content with patterns such as
+  `curl ... | sh` or `wget ... | bash`. This rules out the official Homebrew
+  installer; install it by hand if needed.
+- Do not change SSH or Remote Login, the firewall, FileVault, Gatekeeper,
+  System Integrity Protection, networking, disks, boot configuration, or user
+  credentials without an explicit opt-in switch and a prominent warning.
+- The script runs as the login user. Do not add `sudo`, and do not write
+  preferences into root's domain.
+
+## Behavior and Output
+
+- Check the OS and version first; fail with an actionable message on stderr
+  and a nonzero exit status.
+- Restart only the apps whose preferences were changed, once, at the end.
+- Features with significant impact or machine-specific behavior must be
+  disabled by default and run only when explicitly enabled.
+- Mention in the final message anything that needs a logout or a restart to
+  take effect.
+
+## Change Constraints
+
+- Keep changes focused on macOS initialization. Do not add unrelated
+  functionality.
+- Do not perform broad rewrites solely for style. Preserve existing behavior.
+- Clearly state in the delivery notes when a change alters system behavior or
+  security policy.
+
+## Validation
+
+After modifying the script, run at least:
+
+```bash
+bash -n ./*.sh
+```
+
+If ShellCheck is installed, also run:
+
+```bash
+shellcheck ./*.sh
+```
+
+The development machine is usually the target machine. Unless explicitly
+authorized by the user, do not run the script itself or `defaults write` on it
+while testing; check a key with `defaults read` or `defaults read-type`
+instead. List any behavior that could not be safely validated and recommend
+running the script twice on a fresh macOS user account.
+
+## Delivery Notes
+
+When completing a change, briefly describe:
+
+- Which initialization behavior changed.
+- Whether default behavior or system security policy changed.
+- Which static checks or tests were run.
+- Which operations still require validation on a fresh macOS user account.

macos/macos-init.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+
+set -Eeuo pipefail
+
+# Runtime environment
+if [[ "$(uname -s)" != "Darwin" ]]; then
+    echo "Error: this script supports macOS only." >&2
+    exit 1
+fi
+if (( $(sw_vers -productVersion | cut -d. -f1) < 13 )); then
+    echo "Error: this script requires macOS 13 or later." >&2
+    exit 1
+fi
+
+# Show all file extensions in Finder
+# defaults write NSGlobalDomain AppleShowAllExtensions -bool true
+
+# Show the path bar and status bar in Finder
+# defaults write com.apple.finder ShowPathbar -bool true
+# defaults write com.apple.finder ShowStatusBar -bool true
+
+# Search the current folder by default, and use the list view
+# defaults write com.apple.finder FXDefaultSearchScope -string SCcf
+# defaults write com.apple.finder FXPreferredViewStyle -string Nlsv
+
+# Do not warn when changing a file extension
+# defaults write com.apple.finder FXEnableExtensionChangeWarning -bool false
+
+# Keep .DS_Store files off network shares and USB drives
+# defaults write com.apple.desktopservices DSDontWriteNetworkStores -bool true
+# defaults write com.apple.desktopservices DSDontWriteUSBStores -bool true
+
+# Do not show recent applications in the Dock
+# defaults write com.apple.dock show-recents -bool false
+
+# Keep Spaces in a fixed order
+# defaults write com.apple.dock mru-spaces -bool false
+
+# Repeat keys instead of showing the accent popup, and repeat faster
+# defaults write NSGlobalDomain ApplePressAndHoldEnabled -bool false
+# defaults write NSGlobalDomain KeyRepeat -int 2
+# defaults write NSGlobalDomain InitialKeyRepeat -int 25
+
+# Tap to click
+# defaults write com.apple.AppleMultitouchTrackpad Clicking -bool true
+# defaults write com.apple.driver.AppleBluetoothMultitouch.trackpad Clicking -bool true
+# defaults write NSGlobalDomain com.apple.mouse.tapBehavior -int 1
+
+# Expand the save and print dialogs by default
+# defaults write NSGlobalDomain NSNavPanelExpandedStateForSaveMode -bool true
+# defaults write NSGlobalDomain NSNavPanelExpandedStateForSaveMode2 -bool true
+# defaults write NSGlobalDomain PMPrintingExpandedStateForPrint -bool true
+# defaults write NSGlobalDomain PMPrintingExpandedStateForPrint2 -bool true
+
+# Save screenshots as PNG without window shadows to ~/Screenshots
+# mkdir -p "${HOME}/Screenshots"
+# defaults write com.apple.screencapture location -string "${HOME}/Screenshots"
+# defaults write com.apple.screencapture type -string png
+# defaults write com.apple.screencapture disable-shadow -bool true
+
+# Restart the affected apps so the settings above take effect
+# killall Finder Dock SystemUIServer >/dev/null 2>&1 || true
+
+# echo "macOS configuration completed. Log out and back in if tap to click or key repeat does not take effect."