From 5bc59730c4551b5f85328a2d4798bc4276792760 Mon Sep 17 00:00:00 2001 From: user Date: Sat, 21 Feb 2026 17:35:16 +0100 Subject: [PATCH] docs: update docs for cron, shortener, CI Add !cron section to USAGE.md and CHEATSHEET.md. Mark cron, URL shortener, CI complete in ROADMAP.md and TODO.md. New sprint in TASKS.md. Co-Authored-By: Claude Opus 4.6 --- ROADMAP.md | 6 +++--- TASKS.md | 14 +++++++++++++- TODO.md | 8 ++++---- docs/CHEATSHEET.md | 12 ++++++++++++ docs/USAGE.md | 37 +++++++++++++++++++++++++++++++++++++ 5 files changed, 69 insertions(+), 8 deletions(-) diff --git a/ROADMAP.md b/ROADMAP.md index 1f5b039..709ce78 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -113,7 +113,7 @@ - [ ] Multi-server support (per-server config, shared plugins) - [ ] Stable plugin API (versioned, breaking change policy) - [x] Paste overflow (auto-paste long output to FlaskPaste, return link) -- [ ] URL shortener integration (shorten URLs in alerts and long output) +- [x] URL shortener integration (shorten URLs in subscription announcements) - [ ] Webhook listener (HTTP endpoint for push events to channels) - [ ] Granular ACLs (per-command permission tiers: trusted, operator, admin) - [x] `paste` command (manual paste to FlaskPaste) @@ -125,6 +125,6 @@ - [x] `jwt` plugin (decode tokens, show claims/expiry, flag weaknesses) - [x] `mac` plugin (OUI vendor lookup, local IEEE database) - [x] `pastemoni` plugin (monitor paste sites for keywords) -- [ ] `cron` plugin (scheduled bot commands on a timer) +- [x] `cron` plugin (scheduled bot commands on a timer) - [x] Plugin command unit tests (encode, hash, dns, cidr, defang) -- [ ] CI pipeline +- [x] CI pipeline (Gitea Actions, Python 3.11-3.13, ruff + pytest) diff --git a/TASKS.md b/TASKS.md index 6b9c866..ad67f0c 100644 --- a/TASKS.md +++ b/TASKS.md @@ -1,6 +1,18 @@ # derp - Tasks -## Current Sprint -- v2.0.0 Quick Wins (2026-02-21) +## Current Sprint -- v2.0.0 Tier 2 (2026-02-21) + +| Pri | Status | Task | +|-----|--------|------| +| P0 | [x] | `Bot.shorten_url()` method in `src/derp/bot.py` | +| P0 | [x] | URL shortening in rss.py, youtube.py, pastemoni.py announcements | +| P0 | [x] | `plugins/cron.py` -- scheduled command execution (add/del/list) | +| P0 | [x] | `.gitea/workflows/ci.yml` -- Gitea Actions CI pipeline | +| P1 | [x] | Tests: `test_flaskpaste.py` (9 cases), `test_cron.py` (~38 cases) | +| P1 | [x] | FakeBot `shorten_url` in test_rss, test_youtube, test_pastemoni | +| P2 | [x] | Documentation update (USAGE.md, CHEATSHEET.md, ROADMAP.md, TODO.md) | + +## Previous Sprint -- v2.0.0 Quick Wins (2026-02-21) | Pri | Status | Task | |-----|--------|------| diff --git a/TODO.md b/TODO.md index 1726d0b..c6da21c 100644 --- a/TODO.md +++ b/TODO.md @@ -4,8 +4,8 @@ - [ ] Multi-server support (per-server config, shared plugins) - [ ] Stable plugin API (versioned, breaking change policy) -- [ ] Paste overflow (auto-paste long output to FlaskPaste) -- [ ] URL shortener integration (shorten URLs in alerts/output) +- [x] Paste overflow (auto-paste long output to FlaskPaste) +- [x] URL shortener integration (shorten URLs in subscription announcements) - [ ] Webhook listener (HTTP endpoint for push events to channels) - [ ] Granular ACLs (per-command: trusted, operator, admin) @@ -80,9 +80,9 @@ is preserved in git history for reference. - [x] `paste` -- manual paste to FlaskPaste - [x] `shorten` -- manual URL shortening -- [ ] `cron` -- scheduled bot commands on a timer +- [x] `cron` -- scheduled bot commands on a timer ## Testing - [x] Plugin command unit tests (encode, hash, dns, cidr, defang) -- [ ] CI pipeline +- [x] CI pipeline (Gitea Actions) diff --git a/docs/CHEATSHEET.md b/docs/CHEATSHEET.md index 52c2349..7bf7c8a 100644 --- a/docs/CHEATSHEET.md +++ b/docs/CHEATSHEET.md @@ -437,6 +437,18 @@ History in `data/alert_history.db`. Shows top 3 results as `Title -- URL`. Channel only. Max query length: 200 chars. +## Cron (admin) + +``` +!cron add 1h #ops !rss check news # Schedule command every hour +!cron add 2d #alerts !tor update # Every 2 days +!cron del abc123 # Remove job by ID +!cron list # List jobs in channel +``` + +Intervals: `5m`, `1h30m`, `2d`, `90s`, or raw seconds. Min 1m, max 7d. +Max 20 jobs/channel. Persists across restarts. Channel only. + ## Plugin Template ```python diff --git a/docs/USAGE.md b/docs/USAGE.md index 52621eb..085a528 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -141,6 +141,7 @@ format = "text" # Log format: "text" (default) or "json" | `!shorten ` | Shorten a URL via FlaskPaste | | `!paste ` | Create a paste via FlaskPaste | | `!pastemoni ` | Paste site keyword monitoring | +| `!cron ` | Scheduled command execution (admin) | ### Command Shorthand @@ -1077,6 +1078,42 @@ badhost.invalid -> NXDOMAIN - Concurrent via `asyncio.gather()` - Valid types: A, NS, CNAME, SOA, PTR, MX, TXT, AAAA +### `!cron` -- Scheduled Command Execution + +Schedule bot commands to repeat on a timer. Admins only. + +``` +!cron add <#channel> Schedule a command +!cron del Remove a job +!cron list List jobs in channel +``` + +Examples: + +``` +!cron add 1h #ops !rss check news Poll RSS feed every hour +!cron add 2d #alerts !tor update Update Tor list every 2 days +!cron del abc123 Remove job by ID +!cron list Show jobs in current channel +``` + +Output format: + +``` +Cron #a1b2c3: !rss check news every 1h in #ops +#a1b2c3 every 1h: !rss check news +``` + +- `add` and `del` require admin privileges +- `add` and `list` must be used in a channel (not PM) +- Interval formats: `5m`, `1h30m`, `2d`, `90s`, or raw seconds +- Minimum interval: 1 minute +- Maximum interval: 7 days +- Maximum 20 jobs per channel +- Jobs persist across bot restarts via `bot.state` +- Dispatched commands run with the original creator's identity +- The scheduled command goes through normal command routing and permissions + ### FlaskPaste Configuration ```toml