mirror of
https://github.com/awizemann/scarf.git
synced 2026-05-10 10:36:35 +00:00
feat(templates): promote examples/ to templates/<author>/<name>/ catalog layout
Set up the catalog directory structure this branch will fill with community templates. The existing site-status-checker example moves from examples/templates/ to templates/awizemann/site-status-checker/ (tracked by git as a rename so history is preserved). The examples/ directory is removed. New top-level docs: - templates/README.md — landing for folks browsing the catalog on github.com. Lists the current templates and points at the live site. - templates/CONTRIBUTING.md — author-facing submission walkthrough. Requires AGENTS.md, pre-flight with tools/build-catalog.py --check (added in the next commit), one template per PR, don't edit catalog.json (maintainer regenerates it post-merge). ProjectTemplateExampleTemplateTests.locateExample updated to search templates/<author>/<name>/ instead of examples/templates/ — the test still walks up from #filePath to find the repo root so it works in both xcodebuild and Xcode IDE test runs. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Alan Wizemann
Binary file not shown.
@@ -0,0 +1,66 @@
|
||||
# Site Status Checker — Agent Instructions
|
||||
|
||||
This project maintains a daily uptime check for a short list of URLs. The same instructions apply whether you're Hermes, Claude Code, Cursor, Codex, Aider, or any other agent that reads `AGENTS.md`.
|
||||
|
||||
## Project layout
|
||||
|
||||
- `sites.txt` — one URL per line. Lines starting with `#` are comments. This is the source of truth for what to check. **Not shipped with the template** — created on first run (see below).
|
||||
- `status-log.md` — append-only markdown log. Newest run at the top. Each run is a section with the ISO-8601 timestamp as the heading. Also created on first run.
|
||||
- `.scarf/dashboard.json` — Scarf dashboard. **Only the `value` fields of the three stat widgets and the `items` array of the "Watched Sites" list widget should be updated.** The section titles, widget types, and structure must stay intact.
|
||||
|
||||
## First-run bootstrap
|
||||
|
||||
If `sites.txt` doesn't exist in the project root, create it with this starter content and tell the user you did:
|
||||
|
||||
```
|
||||
# One URL per line. Lines starting with # are comments.
|
||||
# Replace these placeholders with the sites you want to watch.
|
||||
https://example.com
|
||||
https://example.org
|
||||
```
|
||||
|
||||
If `status-log.md` doesn't exist, create it with a one-line header:
|
||||
|
||||
```
|
||||
# Site Status Log
|
||||
|
||||
Newest run at the top. Each section is a single check.
|
||||
```
|
||||
|
||||
## What to do when the cron job fires
|
||||
|
||||
The cron job runs this project's "Check site status" prompt. When invoked:
|
||||
|
||||
1. Read `sites.txt` in the project root. Ignore empty lines and `#`-prefixed comments. Expect plain URLs; be tolerant of whitespace around them.
|
||||
2. For each URL, make an HTTP GET request with a 10-second timeout. Follow up to 3 redirects. Treat any 2xx or 3xx response as **up**, anything else (including timeouts and DNS failures) as **down**.
|
||||
3. Build a results table: URL, status (up/down), HTTP code (or error reason), response time in milliseconds.
|
||||
4. Prepend a new section to `status-log.md`:
|
||||
```
|
||||
## <ISO-8601 timestamp>
|
||||
|
||||
| URL | Status | Code | Latency |
|
||||
|-----|--------|------|---------|
|
||||
| … | up | 200 | 142 ms |
|
||||
| … | down | timeout | — |
|
||||
```
|
||||
5. Update `.scarf/dashboard.json`:
|
||||
- `Sites Up` stat widget: `value` = count of up results.
|
||||
- `Sites Down` stat widget: `value` = count of down results.
|
||||
- `Last Checked` stat widget: `value` = the ISO-8601 timestamp you just wrote.
|
||||
- `Watched Sites` list widget `items`: one entry per URL with `text` = URL and `status` = `"up"` or `"down"` (lowercase).
|
||||
6. If the cron job has a `deliver` target set, emit a one-line summary (`3 up, 1 down — example.com timed out`) as the agent's final response so the delivery mechanism picks it up.
|
||||
|
||||
## What not to do
|
||||
|
||||
- Don't modify the structure of `dashboard.json` (section titles, widget types, widget titles, `columns`). Only the values listed above are writable.
|
||||
- Don't truncate `status-log.md` — it's the historical record. If it grows past 1 MB, add a one-line note at the top of the file asking the user to archive it.
|
||||
- Don't invent URLs. If `sites.txt` is empty or missing, leave the dashboard untouched and write a single `status-log.md` entry noting "no sites configured."
|
||||
- Don't run browsers or headless Chrome. Plain HTTP GET is sufficient.
|
||||
|
||||
## When the user asks you things
|
||||
|
||||
- "What's the status of my sites?" — read the top section of `status-log.md` and summarize.
|
||||
- "Add a site" — append the URL to `sites.txt` on its own line. Don't sort or reorder existing entries. Confirm back to the user which URL you added.
|
||||
- "Remove a site" — delete the matching line from `sites.txt`. If multiple match, ask before choosing.
|
||||
- "Run the check now" — do everything in the cron flow above, then summarize the results in chat.
|
||||
- "Why is [site] down?" — read the last 3-5 entries for that URL in `status-log.md` and report any pattern you see (consistent timeouts, intermittent 5xx, DNS failures, etc.). Don't speculate beyond what the log shows.
|
||||
@@ -0,0 +1,33 @@
|
||||
# Site Status Checker
|
||||
|
||||
A minimal uptime watchdog that pings a list of URLs once a day, records pass/fail results, and keeps a simple Scarf dashboard up to date.
|
||||
|
||||
## What you get
|
||||
|
||||
- **`sites.txt`** — one URL per line. This is the source of truth for what the cron job checks. Edit it to add or remove sites.
|
||||
- **`status-log.md`** — the agent's append-only log of check results. New runs append a section at the top.
|
||||
- **`.scarf/dashboard.json`** — Scarf dashboard with live stat widgets (sites up, sites down, last checked), the full list of watched sites with their last-known status, and a usage guide.
|
||||
- **Cron job `Check site status`** — registered (paused) by the installer; tag `[tmpl:awizemann/site-status-checker]`. Runs daily at 9:00 AM when enabled. The prompt tells the agent to read `sites.txt`, check each URL, write results to `status-log.md`, and update the stat widgets in `dashboard.json`.
|
||||
|
||||
## First steps
|
||||
|
||||
1. Open the **Cron** sidebar and enable the `[tmpl:awizemann/site-status-checker] Check site status` job. It's paused on install so nothing runs without your explicit say-so.
|
||||
2. Edit `sites.txt` in your project root — replace the two placeholder URLs with the sites you actually want to watch.
|
||||
3. From the project's dashboard, ask your agent to run the job now: "Run the site status check and update the dashboard."
|
||||
4. Future runs happen automatically at 9 AM daily.
|
||||
|
||||
## Customizing
|
||||
|
||||
- **Change the schedule.** Edit the cron job in the Cron sidebar — the schedule field accepts `30m`, `every 2h`, or standard cron expressions like `0 9 * * *`.
|
||||
- **Change what "down" means.** By default the agent treats any non-2xx HTTP response as down. If you want to check for specific strings in the body (e.g. "Maintenance"), tell the agent in `AGENTS.md` and it will adapt.
|
||||
- **Add alerting.** Set a `deliver` target on the cron job (Discord, Slack, Telegram) — the agent will post the run summary there instead of just writing to `status-log.md`.
|
||||
|
||||
## Uninstalling
|
||||
|
||||
Templates don't auto-uninstall in Scarf 2.2. To remove this one by hand:
|
||||
|
||||
1. Delete this project directory (removes the dashboard, AGENTS.md, sites.txt, status-log.md).
|
||||
2. Remove the project entry from the Scarf sidebar (click the `−` next to the project name).
|
||||
3. Delete the `[tmpl:awizemann/site-status-checker] Check site status` cron job from the Cron sidebar.
|
||||
|
||||
No memory appendix or skills were installed, so nothing else needs cleanup.
|
||||
@@ -0,0 +1,7 @@
|
||||
[
|
||||
{
|
||||
"name": "Check site status",
|
||||
"schedule": "0 9 * * *",
|
||||
"prompt": "Run the site status check for this project. Follow the instructions in AGENTS.md: read sites.txt, HTTP GET each URL, prepend a results section to status-log.md, and update the three stat widgets plus the Watched Sites list items in .scarf/dashboard.json. When done, reply with a one-line summary like '3 up, 1 down — example.com timed out'."
|
||||
}
|
||||
]
|
||||
@@ -0,0 +1,64 @@
|
||||
{
|
||||
"version": 1,
|
||||
"title": "Site Status",
|
||||
"description": "Daily uptime check for your watched URLs. The stat widgets and list update automatically when the cron job runs.",
|
||||
"theme": { "accent": "green" },
|
||||
"sections": [
|
||||
{
|
||||
"title": "Current Status",
|
||||
"columns": 3,
|
||||
"widgets": [
|
||||
{
|
||||
"type": "stat",
|
||||
"title": "Sites Up",
|
||||
"value": 0,
|
||||
"icon": "checkmark.circle.fill",
|
||||
"color": "green",
|
||||
"subtitle": "responded 2xx/3xx"
|
||||
},
|
||||
{
|
||||
"type": "stat",
|
||||
"title": "Sites Down",
|
||||
"value": 0,
|
||||
"icon": "xmark.circle.fill",
|
||||
"color": "red",
|
||||
"subtitle": "non-2xx, timeout, DNS"
|
||||
},
|
||||
{
|
||||
"type": "stat",
|
||||
"title": "Last Checked",
|
||||
"value": "never",
|
||||
"icon": "clock",
|
||||
"color": "blue",
|
||||
"subtitle": "ISO-8601 timestamp"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "Watched Sites",
|
||||
"columns": 1,
|
||||
"widgets": [
|
||||
{
|
||||
"type": "list",
|
||||
"title": "Configured Sites (from sites.txt)",
|
||||
"items": [
|
||||
{ "text": "https://example.com", "status": "unknown" },
|
||||
{ "text": "https://example.org", "status": "unknown" }
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "How to Use",
|
||||
"columns": 1,
|
||||
"widgets": [
|
||||
{
|
||||
"type": "text",
|
||||
"title": "Quick Start",
|
||||
"format": "markdown",
|
||||
"content": "**1.** Enable the `[tmpl:awizemann/site-status-checker] Check site status` cron job in the Cron sidebar. It ships paused — nothing runs until you say so.\n\n**2.** Edit `sites.txt` in this project's folder to replace the placeholder URLs with the sites you actually want to watch.\n\n**3.** Ask your agent: *\"Run the site status check now.\"* The dashboard refreshes and a new entry appears at the top of `status-log.md`.\n\n**4.** Daily at 9 AM the cron job fires automatically. Change the schedule in the Cron sidebar if you want a different cadence.\n\nSee `README.md` and `AGENTS.md` in the project root for the full spec."
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,20 @@
|
||||
{
|
||||
"schemaVersion": 1,
|
||||
"id": "awizemann/site-status-checker",
|
||||
"name": "Site Status Checker",
|
||||
"version": "1.0.0",
|
||||
"minScarfVersion": "2.2.0",
|
||||
"minHermesVersion": "0.9.0",
|
||||
"author": {
|
||||
"name": "Alan Wizemann",
|
||||
"url": "https://github.com/awizemann/scarf"
|
||||
},
|
||||
"description": "A daily uptime check for a short list of URLs. Writes status to status-log.md and updates the dashboard with current counts.",
|
||||
"category": "monitoring",
|
||||
"tags": ["monitoring", "uptime", "cron", "starter"],
|
||||
"contents": {
|
||||
"dashboard": true,
|
||||
"agentsMd": true,
|
||||
"cron": 1
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user