# AGENTS.md

Guidelines for agentic coding assistants working in this repository.

## Repository Overview

- **Type**: Shell script project for Linux Mint XFCE post-installation setup
- **Main scripts**: `post_installation_script/` - Linux Mint XFCE post-installation automation
- **Testing**: `post_installation_script_test/` - Docker/Podman container-based testing
- **No build system**: Pure shell scripts, no package.json/Makefile/Cargo.toml

---

## 1) Build / Lint / Test Commands

### Shell Scripts

```bash
# Syntax check only (no execution)
bash -n path/to/script.sh

# Trace execution (shows each command as it runs)
bash -x path/to/script.sh

# Lint with shellcheck (install with: apt install shellcheck)
shellcheck post_installation_script/*.sh

# Run individual script
bash path/to/script.sh
./script.sh  # requires executable bit: chmod +x script.sh
```

### Container-Based Testing

```bash
# Build test image (Ubuntu 22.04 with useful utilities)
cd post_installation_script_test
bash 01_create_image.sh

# Start interactive container (auto-removed on exit)
bash 02_start_container_with_image.sh

# Inside container - source scripts mounted at /workspace:
bash /workspace/<scriptName>.sh
```

### Single Test Commands (for future languages)

```bash
# Python: pytest path/to/test.py::TestClass::test_method -q
# Node/Jest: npx jest path/to/file.test.js -t "test name regex"
# Node/Vitest: npx vitest run path/to/file.spec.ts -t "test name"
# Go: go test ./pkg/name -run TestFunctionName
# Rust: cargo test test_name -- --exact
# Java/Maven: mvn -Dtest=ClassName#methodName test
# .NET: dotnet test --filter FullyQualifiedName~Namespace.ClassName.MethodName
```

---

## 2) Code Style Guidelines

### Shell Scripts (Primary Language)

- **Shebang**: Use `#!/bin/bash` (not `/bin/sh`) for bash-specific features
- **Safety**: Use `set -euo pipefail` at script start
- **Quotes**: Always use double quotes for variable expansion: `"$VAR"`, never bare `$VAR`
- **Conditionals**: Use `[[ ]]` for tests, not `[ ]`
- **Variables**: Use `readonly` for constants, `local` for function-scoped variables
- **Performance**: Prefer functions over subshells when possible
- **Naming**: Use descriptive function names: `install_fonts()`, `configure_panel()`, `prompt_user()`
- **Errors**: Write to stderr: `echo "Error: $msg" >&2`
- **Exit codes**: 0=success, 1=general error, 2=invalid usage
- **Comments**: Avoid unless explaining non-obvious behavior
- **Constants**: Define at top of script, UPPER_SNAKE_CASE

### General Conventions

- **Formatting**: Use automated formatters (Black/Prettier/gofmt/rustfmt) - commit formatted code
- **Types**: Prefer explicit typing (TypeScript types, Python type hints, Go static types)
- **Naming**:
  - snake_case: variables, functions (`user_id`, `calculate_total`)
  - PascalCase: types/classes (`UserService`, `HttpClient`)
  - UPPER_SNAKE_CASE: constants (`MAX_RETRIES`, `API_BASE_URL`)
- **Imports**: Keep minimal, group logically (stdlib → third-party → local), blank line between groups
- **Functions**: Keep small (<40 lines), single responsibility, pure where possible
- **Error handling**: Fail fast with context, avoid silent failures, use typed errors where supported
- **Tests**: Deterministic, mock external I/O, explicit names like `test_should_return_400_when_missing_field`
- **Resources**: Always clean up with `finally`/`defer` equivalents

---

## 3) Security

- Never commit secrets, API keys, credentials, or tokens
- Use environment variables for sensitive values
- Validate and sanitize all external input
- Run linting (`shellcheck`) before committing shell scripts

---

## 4) Commit Guidelines

- Make small, focused commits with descriptive messages
- Include formatter command in commit message if auto-formatting
- When changing behavior, add or update tests
- Run full test suite before opening PRs

---

## 5) Cursor / Copilot Rules

- `.cursor/rules/`: Not present
- `.cursorrules`: Not present
- `.github/copilot-instructions.md`: Not present

---

## 6) Repo Housekeeping

- Store session logs in `.agents/sessions/` for reference
- When adding new languages, update this file with exact build/test commands

---

## Files Referenced

- `README.md` - Project overview
- `post_installation_script/README.md` - Script usage and details
- `post_installation_script_test/README.md` - Container testing instructions

---

## Quick Checklist for Changes

- [ ] Run `shellcheck` on shell scripts before committing
- [ ] Verify `bash -n` syntax check passes
- [ ] Test script changes in container first
- [ ] No secrets in code - use environment variables
- [ ] Run tests if added for new functionality