lxcafe/.agents/AGENTS.md

AGENTS

I created this `AGENTS.md` to help agentic coding assistants work in this repository. It contains
1) Build / lint / test commands (including how to run a single test) and
2) Code style guidelines and conventions to follow when editing code here.

Repository state
- This repository contains shell scripts for Linux Mint XFCE post-installation setup.
- Main scripts are located in `post_installation_script/` directory.
- Testing infrastructure is in `post_installation_script_test/` (Docker/Podman test containers).
- No build system, package.json, Makefile, or language-specific project files were detected.
- There are no Cursor rules or Copilot instruction files in the repo (checked paths below).
  - `.cursor/rules/` : not found
  - `.cursorrules` : not found
  - `.github/copilot-instructions.md` : not found

If you add new code (Go, Python, Node, Rust, Java, etc.), follow the per-ecosystem quick commands below.

1) Build / Lint / Test commands

- General notes
  - Run commands from the repository root unless a submodule or service has its own README.
  - Prefer local, repo-scoped toolchains (venv, node_modules/.bin, go modules, cargo) to avoid global state.

- Shell scripts
  - Quick check: `shellcheck scripts/*.sh` (install `shellcheck` first).
  - Run an individual script: `bash path/to/script.sh` or `./script.sh` (ensure executable bit set).
  - Syntax check: `bash -n path/to/script.sh`
  - Trace execution: `bash -x path/to/script.sh` (shows each command as it runs)

- Testing shell scripts
  - See `post_installation_script_test/README.md` for detailed container-based testing instructions.
  - Quick start:
    - Build image: `./post_installation_script_test/01_create_image.sh`
    - Start container: `./post_installation_script_test/02_start_container_with_image.sh`

- Python (if added)
  - Install: `python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt`
  - Lint: `ruff .` or `flake8 .`
  - Format: `black .`
  - Test all: `pytest -q`
  - Run a single test: `pytest path/to/test_file.py::TestClass::test_method -q`

- Node / JavaScript / TypeScript (if added)
  - Install: `npm ci` or `pnpm install` / `yarn install`
  - Lint: `npm run lint` (or `npx eslint .`)
  - Format: `npx prettier --write .`
  - Test all: `npm test` (or `npx vitest` / `npx jest`)
  - Run a single test:
    - Jest: `npx jest path/to/file.test.js -t "test name regex"`
    - Vitest: `npx vitest run path/to/file.spec.ts -t "test name"`

- Go (if added)
  - Build: `go build ./...`
  - Lint: `golangci-lint run` (if configured)
  - Test all: `go test ./...`
  - Run a single test: `go test ./pkg/name -run TestFunctionName`

- Rust (if added)
  - Build: `cargo build`
  - Lint: `cargo clippy`
  - Test all: `cargo test`
  - Run a single test: `cargo test test_name -- --exact`

- Java / Maven (if added)
  - Build: `mvn -DskipTests package`
  - Lint/format: use `spotless`/`checkstyle` if configured
  - Test all: `mvn test`
  - Run a single test: `mvn -Dtest=ClassName#methodName test`

- .NET (if added)
  - Build: `dotnet build`
  - Test all: `dotnet test`
  - Run a single test: `dotnet test --filter FullyQualifiedName~Namespace.ClassName.MethodName`

- CI / Automation
  - If you add GitHub Actions, keep workflows idempotent and cache dependencies carefully.
  - Avoid secrets in workflows; read sensitive values from repository/organization secrets.

2) Code style guidelines

The guidance below is intentionally general and focuses on consistency, readability and safety so
agentic tools can make changes predictably across multiple languages.

- Formatting
  - Use an automated formatter for the language (Black for Python, Prettier for JS/TS, gofmt/gofmt -s for Go,
    rustfmt for Rust). Commit formatted code only.
  - Use an editorconfig file for basic whitespace/indentation rules when possible.

- Imports / dependencies
  - Keep imports explicit and minimal: import only what you use.
  - Group imports in a logical order (language default + third-party + local project). Leave a blank line between groups.
  - Don’t commit unused dependencies; remove them from lock files / manifests and run the linter.

- Types / typing
  - Prefer explicit types where the language supports them (TypeScript types, Python type hints, Go static types).
  - Add types for public interfaces and complex logic; internal simple helper functions may rely on inference.

- Naming conventions
  - Use clear, descriptive names. Prefer `calculate_total`, `prepare_connection`, `user_id` style for snake_case languages.
  - For camelCase languages (JS/TS): `calculateTotal`, `prepareConnection`.
  - Types and classes: use PascalCase/UpperCamelCase: `UserService`, `HttpClient`.
  - Constants: use UPPER_SNAKE_CASE or language-specific constant conventions.

- Functions and modules
  - Keep functions small (ideally < 40 lines) and single-responsibility.
  - Prefer pure functions where possible; keep side effects explicit and isolated.
  - Organize modules by feature/domain, not solely by type (avoid monolithic god-modules).

- Error handling
  - Fail fast and return/raise errors with context (message + cause) rather than swallowing them.
  - Avoid logging raw errors in library code; return errors to callers and let the application layer decide logging.
  - Use typed error types when the language supports it (Go error types, custom exceptions in Python/JS).
  - Clean up resources with `finally`/`defer` equivalents to avoid leaks.

- Tests
  - Prefer small, deterministic unit tests. Mock external IO and network where reasonable.
  - Use explicit fixtures and avoid implicit global state between tests.
  - Name tests with the behavior they assert: `test_calculate_total_with_discounts` or `shouldReturn400WhenMissingField`.

- Logging and observability
  - Use structured logging where available (JSON structured logs for services).
  - Avoid printing raw stack traces to stdout in production code; include them at debug level.

- Security and secrets
  - Never commit secrets, API keys, or credentials. Use environment variables and vaults.
  - Validate and sanitize external input at the boundaries of the system.

- Performance
  - Measure before optimizing. Prefer clarity over micro-optimizations unless a hotspot is identified.

3) Code review / commit guidance for agents

- Make small, focused commits and include a one-line summary plus a short description of the why.
- When changing behavior, add or update tests that verify the new/changed behavior.
- If you reformat files automatically, include the formatter command in the commit message to make CI reproduction easy.

4) Repo housekeeping checks (recommended for agents)

- When adding a new language or framework, add an entry to this file with the exact commands required to build/test.
- Add CI workflows to run lint + tests on PRs and enable branch protection rules if this becomes a shared repo.

5) Cursor / Copilot rules

- Cursor rules: none present at `.cursor/rules/` or `.cursorrules` in this repository.
- GitHub Copilot instructions: none present at `.github/copilot-instructions.md`.

If you add any of these files, update this document and include the exact file path and relevant sections for agents to follow.

Quick checklist for an agent making changes
- Run local linter/formatter configured for the language before opening a PR.
- Run the test suite and the single-test command for any tests you added/changed.
- Do not add secrets to the tree; use placeholders and document required environment variables.

Next steps (recommended)
1) Add a minimal `Makefile` or `package.json` scripts for common tasks so agents can run `make test` / `npm test`.
2) If the project will contain multiple services, add per-service README files and CI workflows.
3) Add EditorConfig + language-specific formatter configs (pyproject.toml, .prettierrc, rustfmt.toml) to lock formatting rules.

Files referenced
- Root `README.md`
- `post_installation_script/README.md` - main script usage
- `post_installation_script_test/README.md` - testing instructions
- `.cursor/rules/` (not present)
- `.cursorrules` (not present)
- `.github/copilot-instructions.md` (not present)

If anything in this file needs to be stricter or you want another style (for example a fully opinionated TS style), say which language or style and I will update `AGENTS.md` accordingly.