123 lines
5.3 KiB
Markdown
123 lines
5.3 KiB
Markdown
# AGENTS.md
|
|
|
|
## Project Overview
|
|
|
|
This project maintains a single shell script for initializing a newly installed
|
|
Debian system. Except for this file and essential project documentation, do not
|
|
split functionality into additional scripts, configuration generators, or other
|
|
languages. Keep the initialization logic centralized, easy to review, and
|
|
directly executable on the target machine.
|
|
|
|
## Scope
|
|
|
|
This file applies to the entire repository.
|
|
|
|
## Target Machine
|
|
|
|
- During development, debugging, and validation, you may connect to the target
|
|
machine with `ssh 192.168.122.130`.
|
|
- When the current user lacks sufficient privileges on the target machine, you
|
|
may elevate privileges with `sudo`.
|
|
|
|
## Development Principles
|
|
|
|
- Write Bash and use `#!/usr/bin/env bash` as the first line.
|
|
- New code must be compatible with the current Debian stable release. If a
|
|
command or option requires a specific version, document it in a comment or
|
|
the README.
|
|
- The script must support repeated execution. Creating users, installing
|
|
packages, writing configuration, and enabling services should be idempotent
|
|
wherever possible. Avoid duplicate entries and failures caused by resources
|
|
that already exist.
|
|
- Keep the single-script design. Prefer small functions with clear
|
|
responsibilities and use a `main` function as the entry point.
|
|
- Prefer `set -Eeuo pipefail`, and explicitly handle commands that may be
|
|
expected to fail.
|
|
- Double-quote variables unless word splitting or glob expansion is
|
|
intentionally required. Use `local` for local variables and clear names for
|
|
constants and environment variables.
|
|
- Prefer native Debian tools and repositories. Do not introduce third-party
|
|
repositories, runtimes, or external dependencies without a valid reason.
|
|
- Comments should explain reasons, compatibility constraints, or risks rather
|
|
than restating each line of code.
|
|
|
|
## Security Requirements
|
|
|
|
- Check for root privileges before operations that require them and provide a
|
|
clear error message. Do not silently elevate privileges inside the script.
|
|
- 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`.
|
|
- Download external files over HTTPS and verify fixed versions, checksums, or
|
|
signatures whenever possible.
|
|
- Confirm target files and directories before changing system configuration.
|
|
When replacing important configuration, preserve a recoverable backup or use
|
|
a reviewable atomic write.
|
|
- Avoid broad or irreversible commands, including recursive deletion with
|
|
unvalidated variables, globally relaxed permissions, and unconditional
|
|
firewall resets.
|
|
- Do not change SSH login policy, network connectivity, disk partitions, boot
|
|
configuration, or existing user credentials without explicit authorization.
|
|
If the project explicitly requires such an operation, provide a prominent
|
|
warning and an explicit opt-in switch.
|
|
- Scope noninteractive APT settings to only the commands that require them. Do
|
|
not permanently change the user's environment.
|
|
|
|
## Behavior and Output
|
|
|
|
- Early in startup, check the runtime environment, Debian version, privileges,
|
|
and required commands. Fail with actionable error messages.
|
|
- Print concise and clear status messages for important steps. Write errors to
|
|
standard error and exit with a nonzero status.
|
|
- Prefer environment variables with safe defaults or command-line options for
|
|
user-selectable features, and provide `--help`. Do not unexpectedly block
|
|
unattended execution.
|
|
- Features with significant impact or machine-specific behavior must be
|
|
disabled by default and run only when explicitly enabled.
|
|
- Combine package installation into as few `apt-get install` operations as
|
|
practical, and avoid unnecessary `apt-get upgrade` or distribution upgrades.
|
|
- Do not assume a systemd service exists. Confirm that the relevant package and
|
|
service unit are available before enabling or restarting a service.
|
|
|
|
## Change Constraints
|
|
|
|
- Keep changes focused on Debian initialization. Do not add unrelated
|
|
functionality.
|
|
- Do not perform broad rewrites solely for style. Preserve existing behavior
|
|
and configuration options.
|
|
- Give new configuration options safe defaults and update script help and
|
|
related documentation.
|
|
- Clearly state in the delivery notes when a change alters system behavior,
|
|
default packages, or security policy.
|
|
|
|
## Validation
|
|
|
|
After modifying the script, run at least:
|
|
|
|
```bash
|
|
bash -n ./*.sh
|
|
```
|
|
|
|
If ShellCheck is installed, also run:
|
|
|
|
```bash
|
|
shellcheck ./*.sh
|
|
```
|
|
|
|
For argument parsing or pure function logic, use temporary directories and
|
|
mock input for targeted tests. Unless explicitly authorized by the user, do not
|
|
install or remove packages, modify `/etc`, manage users, change networking,
|
|
restart services, or reboot the current development machine during testing.
|
|
List any system-level behavior that cannot be safely validated and recommend
|
|
validation steps in a fresh Debian virtual machine.
|
|
|
|
## 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 in a fresh Debian virtual machine.
|