49 lines
2.5 KiB
Markdown
49 lines
2.5 KiB
Markdown
# AI Coding Agent Instructions for slackecho
|
|
|
|
## Project Overview
|
|
**slackecho** is a minimal bash shell script that sends messages to Slack via incoming webhooks using `curl`. The project intentionally keeps scope small: message delivery only, no dependencies beyond curl.
|
|
|
|
## Architecture & Key Components
|
|
- **Single Script**: `slackecho` - standalone bash executable with no external modules
|
|
- **Integration Method**: Slack Incoming Webhooks (posts JSON payload via HTTP POST)
|
|
- **Minimal Scope**: Script handles message delivery; does not manage authentication, logging, or retries
|
|
|
|
**Key Design Decision**: This is a "do one thing well" utility meant for shell script integration (e.g., reporting from cron jobs or CI/CD pipelines). Avoid adding features that expand scope beyond message transmission.
|
|
|
|
## Setup & Execution
|
|
1. **Configuration**: Currently hardcoded `SLACKURL` in the script (TODO: move to external config file)
|
|
2. **Installation**: Copy `slackecho` to a system binary path (e.g., `/usr/local/bin/`)
|
|
3. **Dependency**: Requires `curl` to be installed
|
|
|
|
## Command Signature
|
|
```bash
|
|
slackecho <message> [username] [channel] [icon]
|
|
```
|
|
|
|
- `message` (required): Text to send
|
|
- `username`: Slack display name (default: "slackecho-user")
|
|
- `channel`: Target channel (default: "general")
|
|
- `icon`: Emoji icon (default: ":robot_face:")
|
|
|
|
## Patterns & Conventions
|
|
- **Parameter Handling**: Arguments passed positionally; optional parameters checked with empty string tests (`[ "$2" = "" ]`)
|
|
- **Curl Usage**: Single POST request with URL-encoded JSON payload; output suppressed to `/dev/null`
|
|
- **Error Handling**: Currently minimal—no validation of Slack URL or message content; POST failures silently ignored
|
|
- **Default Values**: All four parameters have sensible defaults defined within script
|
|
|
|
## Common Modifications
|
|
When adding features, maintain the philosophy of simplicity:
|
|
- **Configuration File**: TODO item suggests moving hardcoded `SLACKURL` to external config
|
|
- **Tests**: Currently N/A; any test framework should be lightweight (e.g., BATS for bash)
|
|
- **Logging**: Not currently implemented; if added, should be optional/minimal
|
|
|
|
## Important TODOs
|
|
1. Create external configuration file (move `SLACKURL` and defaults)
|
|
2. Add test framework (likely bash-based)
|
|
3. Add code review process
|
|
4. Document contribution guidelines
|
|
|
|
## References
|
|
- Slack Incoming Webhooks: Uses Slack's webhook JSON format with `channel`, `username`, `text`, `icon_emoji` fields
|
|
- Repository Maintainer: gary@hansenit.solutions
|