diff --git a/.agents/AGENTS.md b/.agents/AGENTS.md index beac5e9..a62e515 100644 --- a/.agents/AGENTS.md +++ b/.agents/AGENTS.md @@ -1,169 +1,140 @@ -AGENTS +# AGENTS.md -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. +Guidelines for agentic coding assistants working in this repository. -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 +## Repository Overview -If you add new code (Go, Python, Node, Rust, Java, etc.), follow the per-ecosystem quick commands below. +- **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 +--- -- 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. +## 1) Build / Lint / Test Commands -- 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) +### Shell Scripts -- 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` +```bash +# Syntax check only (no execution) +bash -n path/to/script.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` +# Trace execution (shows each command as it runs) +bash -x path/to/script.sh -- 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"` +# Lint with shellcheck (install with: apt install shellcheck) +shellcheck post_installation_script/*.sh -- 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` +# Run individual script +bash path/to/script.sh +./script.sh # requires executable bit: chmod +x script.sh +``` -- Rust (if added) - - Build: `cargo build` - - Lint: `cargo clippy` - - Test all: `cargo test` - - Run a single test: `cargo test test_name -- --exact` +### Container-Based Testing -- 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` +```bash +# Build test image (Ubuntu 22.04 with useful utilities) +cd post_installation_script_test +bash 01_create_image.sh -- .NET (if added) - - Build: `dotnet build` - - Test all: `dotnet test` - - Run a single test: `dotnet test --filter FullyQualifiedName~Namespace.ClassName.MethodName` +# Start interactive container (auto-removed on exit) +bash 02_start_container_with_image.sh -- 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. +# Inside container - source scripts mounted at /workspace: +bash /workspace/.sh +``` -2) Code style guidelines +### Single Test Commands (for future languages) -The guidance below is intentionally general and focuses on consistency, readability and safety so -agentic tools can make changes predictably across multiple 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 +``` -- 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. +## 2) Code Style Guidelines -- 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. +### Shell Scripts (Primary Language) -- 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. +- **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 -- 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). +### General Conventions -- 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. +- **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 -- 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. +## 3) Security -- 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. +- 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 -- Performance - - Measure before optimizing. Prefer clarity over micro-optimizations unless a hotspot is identified. +--- -3) Code review / commit guidance for agents +## 4) Commit Guidelines -- 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. +- 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 -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. -- **Session storage**: Store session logs and working notes in `.agents/sessions/` folder for future reference. Use descriptive filenames (e.g., `session--.md`). +## 5) Cursor / Copilot Rules -5) Cursor / Copilot rules +- `.cursor/rules/`: Not present +- `.cursorrules`: Not present +- `.github/copilot-instructions.md`: Not present -- 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. +## 6) Repo Housekeeping -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. +- Store session logs in `.agents/sessions/` for reference +- When adding new languages, update this file with exact build/test commands -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) +## Files Referenced -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. +- `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 diff --git a/post_installation_script/Nachinstallationsarbeiten_LC_Esslingen_XFCE.sh b/post_installation_script/Nachinstallationsarbeiten_LC_Esslingen_XFCE.sh index eab30b8..73b805f 100644 --- a/post_installation_script/Nachinstallationsarbeiten_LC_Esslingen_XFCE.sh +++ b/post_installation_script/Nachinstallationsarbeiten_LC_Esslingen_XFCE.sh @@ -114,24 +114,25 @@ echo " ## Microsoft Aptos Schriftarten installieren:" if question_answered_with_yes " ### Installiere Aptos Schriften? ###"; then echo echo "### Aptos Schriften ###" - + _aptos_zip="Microsoft Aptos Fonts.zip" - if [ ! -f "$_aptos_zip" ]; then - echo "" - echo "$_aptos_zip nicht gefunden." - echo "Bitte laden Sie die Datei von Microsoft herunter und legen Sie sie im selben Verzeichnis wie dieses Skript ab." - else - echo - echo "Entpacke das Archiv..." - unzip -o "$_aptos_zip" - echo "Erstelle /usr/share/fonts/truetype/aptos/" - sudo mkdir -p /usr/share/fonts/truetype/aptos - echo "Installiere alle .ttf Schriften..." - find . -name "*.ttf" -exec sudo install -m644 {} /usr/share/fonts/truetype/aptos/ \; 2>/dev/null || true - echo "Aktualisiere den Font-Cache" - fc-cache -f - echo "Fertig! Aptos Schriftarten sind installiert." - fi + _aptos_url="https://download.microsoft.com/download/8/6/0/860a94fa-7feb-44ef-ac79-c072d9113d69/Microsoft%20Aptos%20Fonts.zip" + + echo "Lade Aptos Schriften herunter..." + wget "$_aptos_url" -O "$_aptos_zip" + + echo "Entpacke das Archiv..." + unzip -o "$_aptos_zip" + echo "Erstelle /usr/share/fonts/truetype/aptos/" + sudo mkdir -p /usr/share/fonts/truetype/aptos + echo "Installiere alle .ttf Schriften..." + find . -name "*.ttf" -exec sudo install -m644 {} /usr/share/fonts/truetype/aptos/ \; 2>/dev/null || true + echo "Aktualisiere den Font-Cache" + fc-cache -f + echo "Fertig! Aptos Schriftarten sind installiert." + + echo "Entferne temporäre Dateien..." + rm -f "$_aptos_zip" fi echo