mirror of
https://codeberg.org/knightsub9/lxcafe.git
synced 2026-07-19 19:30:16 +02:00
141 lines
4.6 KiB
Markdown
141 lines
4.6 KiB
Markdown
# 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
|