91 lines
3.5 KiB
Markdown
91 lines
3.5 KiB
Markdown
# 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.
|