Two files, one repository

ANDRS-Projects/cloudflare-uptime-oss ships 2 formats across 2 indexed files. The question worth asking is whether the second one says anything the first does not.

CompareAGENTS.md ↔ CLAUDE.md

A · AGENTS.md · 1492 words B · CLAUDE.md · 40 words

What each file covers, counted
Dimension	Shared	Only in A	Overlap
Sections	1	11	8%
Commands	0	10	0%
Section tags	0	6	0%

What each file covers

Sections

1 shared · 11 only in A · 0 only in B

− What
− Quick Start
− Commands
− Development
− Schema
− Deploy
− Architecture
− Key Files
− Configuration
− Gotchas for AI Assistants
− Contributing
cloudflare-uptime

Commands

0 shared · 10 only in A · 0 only in B

− npm install
− npm run deploy
− npm run dev
− npm run typecheck
− npm run db:init
− npm run db:init:remote
− tsc --noEmit
− npx tsx
− node --check
− npm ci

Section tags

0 shared · 6 only in A · 0 only in B

− setup
− code-style
− types
− database
− performance
− deployment

Line diff

+3 added−165 removed3 unchanged1.8% identical

ANDRS-Projects/cloudflare-uptime-oss · AGENTS.md

@@ −1 @@

1# cloudflare-uptime

3**Version:** 1.6.4 | **Runtime:** Cloudflare Workers | **Stack:** TypeScript + Hono + D1 + R2

5This file is the canonical set of instructions for AI coding agents working in this repo

6(Claude Code, Cursor, Copilot, Codex, etc.). If your tool reads a vendor-specific file

7instead (e.g. `CLAUDE.md`), that file just points back here — keep this one up to date,

8not a duplicate.

10## What

12Self-hosted uptime monitoring on Cloudflare Workers. Cron checks run every minute (configurable),

13store results in D1, and serve public status pages with 90-day latency history and an RSS feed.

14No servers. No monthly fees beyond the Cloudflare free tier.

16## Quick Start

18```bash

19npm install # Install dependencies

20wrangler d1 create uptime-monitor # Create D1 — paste ID into wrangler.toml

21wrangler d1 execute uptime-monitor --file=schema.sql # Apply schema (local)

22wrangler r2 bucket create uptime-assets # Create R2 bucket

23wrangler secret put API_KEY # Set admin auth secret

24npm run deploy # Deploy to Cloudflare

25```

27Or run the interactive bootstrap: `./setup.sh`

29## Commands

31```bash

32# Development

33npm install # Install dependencies

34npm run dev # Local dev (wrangler dev)

35npm run typecheck # tsc --noEmit — run this before committing

37# Schema

38npm run db:init # Apply schema.sql (local D1)

39npm run db:init:remote # Apply schema.sql (remote D1)

41# Deploy

42npm run deploy # Deploy Worker to Cloudflare

43```

45There is no automated test suite. `npm run typecheck` plus manual verification (see the

46escaping gotcha below for why typecheck alone isn't always enough) is the check to run

47before committing.

49## Architecture

51```

52src/

53 worker.ts # Hono app — all route registrations, custom domain middleware, scheduled() dispatch

54 cron.ts # ScheduledEvent handler (the * * * * * trigger) — runs checks, fires alerts, daily cleanup

55 health.ts # ScheduledEvent handler (the */15 * * * * trigger) — self-monitoring staleness check

56 checks.ts # HTTP check runner (fetch + AbortController timeout)

57 alerts.ts # Slack/Discord webhook payload builders (per-monitor and self-monitoring)

58 db.ts # All D1 query functions (single source of truth for SQL)

59 types.ts # Shared TypeScript interfaces (Env, Monitor, Check, Incident…)

60 api/

61 monitors.ts # CRUD for monitors

62 pages.ts # CRUD for status pages + monitor assignments

63 notices.ts # Maintenance notice lifecycle

64 public.ts # Unauthenticated status page data endpoint

65 rss.ts # RSS feed generator

66 upload.ts # R2 logo upload/delete

67 html/

68 admin.ts # Admin dashboard (inline HTML/JS, no build step — see gotcha below)

69 status.ts # Public status page shell (fetches /status/:slug/data at runtime)

70schema.sql # Full D1 schema — run once with wrangler d1 execute

71wrangler.toml # Worker config: D1 binding, R2 binding, cron schedules, routes

72```

74Admin dashboard at `/` (auth via `X-API-Key` header). Public status pages at `/status/:slug`.

75Custom domain routing: the `*` middleware maps an incoming hostname to its status page slug via D1.

77## Key Files

79```

80wrangler.toml # Change database_id after `wrangler d1 create`, add custom routes here

81schema.sql # Run this once — NOT auto-applied on deploy

82src/worker.ts # Route table, custom domain middleware, and scheduled() dispatch by event.cron

83src/cron.ts # Check interval + stagger-offset logic (see gotcha below)

84src/health.ts # Self-monitoring staleness check — runs on its own cron, never touches the hot path

85src/db.ts # Every D1 query — start here when debugging data issues

86src/types.ts # Env interface (DB: D1Database, ASSETS: R2Bucket, API_KEY, HEALTH_ALERT_WEBHOOK)

87src/checks.ts # What "ok" means: HTTP 200–399; anything else (including timeout) is down

88src/alerts.ts # Webhook format: Slack/Discord compatible attachments payload

89```

91## Configuration

94|--------------------|-----------|----------|-------------|

95| `API_KEY` | `wrangler secret put API_KEY` | Yes | Admin auth — all `/api/*` routes check `X-API-Key` header |

103

104## Gotchas for AI Assistants

105

106- **Schema migrations are manual.** `wrangler deploy` does NOT run `schema.sql`. Use

107 `wrangler d1 execute uptime-monitor --remote --file=schema.sql` for the initial apply.

108 Subsequent changes go in a numbered `migrations/NNN_*.sql` file, applied with

109 `wrangler d1 migrations apply uptime-monitor --remote`. Always apply the migration

110 *before* deploying code that depends on it — if a migration adds a table that cron

111 writes to on every check, deploying first means cron errors on that write until the

112 migration catches up. `deploy.yml` here does not apply migrations automatically.

113- **`src/html/admin.ts` nests a full `<script>` block inside a returned template-literal

114 string — escape sequences behave differently than they look.** `admin.ts` returns one

115 big JS string containing literal HTML, which itself contains a `<script>` block of

116 literal JS text. Any `\'` or similar escape you write in that inline JS gets resolved

117 by the *outer* TypeScript template literal before it ever becomes a string — the

118 backslash is silently consumed, and what actually reaches the browser is unescaped.

119 This broke admin login in production once (an apostrophe in banner text closed a JS

120 string early, breaking the whole inline `<script>` parse) and `tsc --noEmit` did not

121 catch it, because the broken JS lives inside a string literal that TypeScript never

122 parses as code. If you touch the inline JS in `admin.ts` (or `status.ts`) and it needs

123 an apostrophe or backslash, either avoid it (reword) or verify by actually rendering

124 the function's output and syntax-checking the real `<script>` content — e.g.

125 `npx tsx` to call `renderAdmin(true)`, extract the `<script>...</script>` block from

126 the output, and run `node --check` on it. Don't rely on `tsc --noEmit` alone for this

127 file.

128- **No frontend build step.** All HTML is returned as template-literal strings from

129 `src/html/admin.ts` and `src/html/status.ts`. Do not introduce a bundler.

130- **`workers_dev = true`** in `wrangler.toml` exposes the Worker on a `.workers.dev` URL.

131 Custom domains are added via `[[routes]]` blocks — each requires `custom_domain = true`

132 and the domain must be proxied through Cloudflare DNS.

133- **Cron runs from one datacenter**, not globally. D1 latency is lowest when the cron

134 datacenter is geographically close to your D1 region.

135- **`interval_minutes` is checked by modulo plus a per-monitor stagger offset, not a

136 plain modulo.** `cron.ts` computes a deterministic hash-based offset from `monitor.id`

137 and checks `(minuteOfDay + checkOffset(...)) % interval_minutes === 0`. Each monitor

138 still runs exactly once per `interval_minutes`, just at a different phase — this

139 exists so monitors sharing a common-multiple interval (1/5/10/30 all divide 30) don't

140 all land in the same cron tick at once. Don't "simplify" this back to plain modulo.

141- **The Workers Free plan hard-caps CPU time at 10ms per invocation.** This is a real

142 constraint, not a soft limit — a cron tick checking many monitors can genuinely run out

143 of budget. `cron.ts` batches all due monitors' D1 writes/reads into a couple of

144 round-trips per tick (not one per monitor) specifically to stay under this. If you add

145 a new per-monitor D1 call inside the cron loop, batch it across all due monitors rather

146 than calling it once per monitor in a loop — the fixed dispatch overhead per D1 call is

147 what blows the budget, not D1's own query time.

148- **`src/health.ts` runs on a separate, independent cron trigger (`*/15 * * * *`) and

149 must never be merged into or add cost to the `* * * * *` check-loop tick** — it exists

150 specifically to detect when that tick stops completing, so it can't depend on it.

151- **Checks table has a 90-day rolling window.** The cleanup in `cron.ts` deletes rows older

152 than 90 days once per day (at midnight UTC); `uptime_bucket_rollups` is cleaned the same way.

153- **`alert_webhook` is stored per-monitor** (not per status page). Set it to a Slack or

154 Discord incoming webhook URL to receive up/down alerts. `HEALTH_ALERT_WEBHOOK` is a

155 separate, account-level secret for self-monitoring alerts — don't conflate the two.

156- **Regenerating `package-lock.json` from scratch (`rm -f package-lock.json && npm install`)

157 can silently produce an incomplete lockfile** missing optional platform-variant entries

158 (`@esbuild/*`, `@img/sharp-*`, `@cloudflare/workerd-*` for platforms other than the one

159 that generated it). `npm ci` requires full cross-platform consistency and will fail on

160 a genuinely clean checkout (i.e. in CI) even though `npm ci` succeeds locally against

161 that same file — it's self-consistent with itself, which isn't the same thing. When

162 bumping a dependency, prefer editing `package.json` and running a plain `npm install`

163 on top of the existing lockfile (incremental update) over deleting it first.

164

165## Contributing

166

167See [CONTRIBUTING.md](CONTRIBUTING.md).

168

ANDRS-Projects/cloudflare-uptime-oss · CLAUDE.md

@@ +1 @@

1# cloudflare-uptime

3See [AGENTS.md](AGENTS.md) — that's the canonical instructions file for AI coding

4agents working in this repo (Claude Code, Cursor, Copilot, Codex, etc.). Keeping one

5canonical file instead of duplicating content here avoids the two drifting out of sync.

@@ −1 +1 @@

11 # cloudflare-uptime

3−**Version:** 1.6.4 | **Runtime:** Cloudflare Workers | **Stack:** TypeScript + Hono + D1 + R2

4−

5−This file is the canonical set of instructions for AI coding agents working in this repo

6−(Claude Code, Cursor, Copilot, Codex, etc.). If your tool reads a vendor-specific file

7−instead (e.g. `CLAUDE.md`), that file just points back here — keep this one up to date,

8−not a duplicate.

9−

10−## What

11−

12−Self-hosted uptime monitoring on Cloudflare Workers. Cron checks run every minute (configurable),

13−store results in D1, and serve public status pages with 90-day latency history and an RSS feed.

14−No servers. No monthly fees beyond the Cloudflare free tier.

15−

16−## Quick Start

17−

18−```bash

19−npm install # Install dependencies

20−wrangler d1 create uptime-monitor # Create D1 — paste ID into wrangler.toml

21−wrangler d1 execute uptime-monitor --file=schema.sql # Apply schema (local)

22−wrangler r2 bucket create uptime-assets # Create R2 bucket

23−wrangler secret put API_KEY # Set admin auth secret

24−npm run deploy # Deploy to Cloudflare

25−```

26−

27−Or run the interactive bootstrap: `./setup.sh`

28−

29−## Commands

30−

31−```bash

32−# Development

33−npm install # Install dependencies

34−npm run dev # Local dev (wrangler dev)

35−npm run typecheck # tsc --noEmit — run this before committing

36−

37−# Schema

38−npm run db:init # Apply schema.sql (local D1)

39−npm run db:init:remote # Apply schema.sql (remote D1)

40−

41−# Deploy

42−npm run deploy # Deploy Worker to Cloudflare

43−```

44−

45−There is no automated test suite. `npm run typecheck` plus manual verification (see the

46−escaping gotcha below for why typecheck alone isn't always enough) is the check to run

47−before committing.

48−

49−## Architecture

50−

51−```

52−src/

53− worker.ts # Hono app — all route registrations, custom domain middleware, scheduled() dispatch

54− cron.ts # ScheduledEvent handler (the * * * * * trigger) — runs checks, fires alerts, daily cleanup

55− health.ts # ScheduledEvent handler (the */15 * * * * trigger) — self-monitoring staleness check

56− checks.ts # HTTP check runner (fetch + AbortController timeout)

57− alerts.ts # Slack/Discord webhook payload builders (per-monitor and self-monitoring)

58− db.ts # All D1 query functions (single source of truth for SQL)

59− types.ts # Shared TypeScript interfaces (Env, Monitor, Check, Incident…)

60− api/

61− monitors.ts # CRUD for monitors

62− pages.ts # CRUD for status pages + monitor assignments

63− notices.ts # Maintenance notice lifecycle

64− public.ts # Unauthenticated status page data endpoint

65− rss.ts # RSS feed generator

66− upload.ts # R2 logo upload/delete

67− html/

68− admin.ts # Admin dashboard (inline HTML/JS, no build step — see gotcha below)

69− status.ts # Public status page shell (fetches /status/:slug/data at runtime)

70−schema.sql # Full D1 schema — run once with wrangler d1 execute

71−wrangler.toml # Worker config: D1 binding, R2 binding, cron schedules, routes

72−```

73−

74−Admin dashboard at `/` (auth via `X-API-Key` header). Public status pages at `/status/:slug`.

75−Custom domain routing: the `*` middleware maps an incoming hostname to its status page slug via D1.

76−

77−## Key Files

78−

79−```

80−wrangler.toml # Change database_id after `wrangler d1 create`, add custom routes here

81−schema.sql # Run this once — NOT auto-applied on deploy

82−src/worker.ts # Route table, custom domain middleware, and scheduled() dispatch by event.cron

83−src/cron.ts # Check interval + stagger-offset logic (see gotcha below)

84−src/health.ts # Self-monitoring staleness check — runs on its own cron, never touches the hot path

85−src/db.ts # Every D1 query — start here when debugging data issues

86−src/types.ts # Env interface (DB: D1Database, ASSETS: R2Bucket, API_KEY, HEALTH_ALERT_WEBHOOK)

87−src/checks.ts # What "ok" means: HTTP 200–399; anything else (including timeout) is down

88−src/alerts.ts # Webhook format: Slack/Discord compatible attachments payload

89−```

90−

91−## Configuration

92−

94−|--------------------|-----------|----------|-------------|

95−| `API_KEY` | `wrangler secret put API_KEY` | Yes | Admin auth — all `/api/*` routes check `X-API-Key` header |

103−

104−## Gotchas for AI Assistants

105−

106−- **Schema migrations are manual.** `wrangler deploy` does NOT run `schema.sql`. Use

107− `wrangler d1 execute uptime-monitor --remote --file=schema.sql` for the initial apply.

108− Subsequent changes go in a numbered `migrations/NNN_*.sql` file, applied with

109− `wrangler d1 migrations apply uptime-monitor --remote`. Always apply the migration

110− *before* deploying code that depends on it — if a migration adds a table that cron

111− writes to on every check, deploying first means cron errors on that write until the

112− migration catches up. `deploy.yml` here does not apply migrations automatically.

113−- **`src/html/admin.ts` nests a full `<script>` block inside a returned template-literal

114− string — escape sequences behave differently than they look.** `admin.ts` returns one

115− big JS string containing literal HTML, which itself contains a `<script>` block of

116− literal JS text. Any `\'` or similar escape you write in that inline JS gets resolved

117− by the *outer* TypeScript template literal before it ever becomes a string — the

118− backslash is silently consumed, and what actually reaches the browser is unescaped.

119− This broke admin login in production once (an apostrophe in banner text closed a JS

120− string early, breaking the whole inline `<script>` parse) and `tsc --noEmit` did not

121− catch it, because the broken JS lives inside a string literal that TypeScript never

122− parses as code. If you touch the inline JS in `admin.ts` (or `status.ts`) and it needs

123− an apostrophe or backslash, either avoid it (reword) or verify by actually rendering

124− the function's output and syntax-checking the real `<script>` content — e.g.

125− `npx tsx` to call `renderAdmin(true)`, extract the `<script>...</script>` block from

126− the output, and run `node --check` on it. Don't rely on `tsc --noEmit` alone for this

127− file.

128−- **No frontend build step.** All HTML is returned as template-literal strings from

129− `src/html/admin.ts` and `src/html/status.ts`. Do not introduce a bundler.

130−- **`workers_dev = true`** in `wrangler.toml` exposes the Worker on a `.workers.dev` URL.

131− Custom domains are added via `[[routes]]` blocks — each requires `custom_domain = true`

132− and the domain must be proxied through Cloudflare DNS.

133−- **Cron runs from one datacenter**, not globally. D1 latency is lowest when the cron

134− datacenter is geographically close to your D1 region.

135−- **`interval_minutes` is checked by modulo plus a per-monitor stagger offset, not a

136− plain modulo.** `cron.ts` computes a deterministic hash-based offset from `monitor.id`

137− and checks `(minuteOfDay + checkOffset(...)) % interval_minutes === 0`. Each monitor

138− still runs exactly once per `interval_minutes`, just at a different phase — this

139− exists so monitors sharing a common-multiple interval (1/5/10/30 all divide 30) don't

140− all land in the same cron tick at once. Don't "simplify" this back to plain modulo.

141−- **The Workers Free plan hard-caps CPU time at 10ms per invocation.** This is a real

142− constraint, not a soft limit — a cron tick checking many monitors can genuinely run out

143− of budget. `cron.ts` batches all due monitors' D1 writes/reads into a couple of

144− round-trips per tick (not one per monitor) specifically to stay under this. If you add

145− a new per-monitor D1 call inside the cron loop, batch it across all due monitors rather

146− than calling it once per monitor in a loop — the fixed dispatch overhead per D1 call is

147− what blows the budget, not D1's own query time.

148−- **`src/health.ts` runs on a separate, independent cron trigger (`*/15 * * * *`) and

149− must never be merged into or add cost to the `* * * * *` check-loop tick** — it exists

150− specifically to detect when that tick stops completing, so it can't depend on it.

151−- **Checks table has a 90-day rolling window.** The cleanup in `cron.ts` deletes rows older

152− than 90 days once per day (at midnight UTC); `uptime_bucket_rollups` is cleaned the same way.

153−- **`alert_webhook` is stored per-monitor** (not per status page). Set it to a Slack or

154− Discord incoming webhook URL to receive up/down alerts. `HEALTH_ALERT_WEBHOOK` is a

155− separate, account-level secret for self-monitoring alerts — don't conflate the two.

156−- **Regenerating `package-lock.json` from scratch (`rm -f package-lock.json && npm install`)

157− can silently produce an incomplete lockfile** missing optional platform-variant entries

158− (`@esbuild/*`, `@img/sharp-*`, `@cloudflare/workerd-*` for platforms other than the one

159− that generated it). `npm ci` requires full cross-platform consistency and will fail on

160− a genuinely clean checkout (i.e. in CI) even though `npm ci` succeeds locally against

161− that same file — it's self-consistent with itself, which isn't the same thing. When

162− bumping a dependency, prefer editing `package.json` and running a plain `npm install`

163− on top of the existing lockfile (incremental update) over deleting it first.

164−

165−## Contributing

166−

167−See [CONTRIBUTING.md](CONTRIBUTING.md).

3+See [AGENTS.md](AGENTS.md) — that's the canonical instructions file for AI coding

4+agents working in this repo (Claude Code, Cursor, Copilot, Codex, etc.). Keeping one

5+canonical file instead of duplicating content here avoids the two drifting out of sync.

1686

Two files, one repository

Built for the same person as RuleStack