lxcafe/.agents/AGENTS.md

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

# 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

# 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)

# 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