Skip to content
Beef Docs

Horns

Horns

Responsibility

Horns is the home for Foxy’s Cloudflare-managed apps — Workers (and, when needed, Pages). Everything else in the beef monorepo deploys on Railway; everything under apps/horns/ runs on Cloudflare’s edge via wrangler. It exists for workloads that fit Cloudflare’s model better than an always-on Railway service: cron-scheduled jobs, lightweight HTTP endpoints, and edge-hosted static sites — with no long-running container to pay for or operate.

Horns is a container, not a single service: each subdirectory is one self-contained Worker/Pages app with its own wrangler.toml, package.json, lockfile, src/, and test/. There is no shared build infrastructure and (deliberately) no shared package yet — each app deploys independently.

How it works

  • Runtime. Workers run on Cloudflare’s V8 isolates, not Node — code targets the Workers runtime (fetch and scheduled handlers), bundled and deployed by wrangler. No Dockerfile, no Railway service.
  • Scheduling. Cron triggers are declared in each app’s wrangler.toml under [triggers] crons. Cloudflare invokes the app’s scheduled() handler once per matching cron expression, and the app routes on controller.cron.
  • State. Durable state uses Cloudflare bindings — KV, D1, R2, Durable Objects — declared in wrangler.toml. Binding names are committed; the namespace ids are created per-account with wrangler and pasted in.
  • Secrets. API keys and tokens are set with wrangler secret put and are never committed. Local wrangler dev reads a gitignored .dev.vars instead.
  • Config and safety. Non-secret runtime flags live in wrangler.toml under [vars]. By convention an app ships with its side effects (posting, writing, sending) gated off — for example a DRY_RUN="1" flag — so a fresh deploy never acts until someone explicitly enables it.

Apps

linear-reports

The first Horns app: a scheduled Linear → Slack reporting framework. One cached Linear read per run feeds three cron-driven workflows that post to a Slack channel (#project-management):

  • weekly-load — a weekly report that leads with points completed per person, then flags in-progress outliers (overloaded / idle). Runs Mondays 07:00 UTC.
  • daily-idle — flags roster members with nothing actively in progress. Runs daily at 07:00 UTC.
  • approval-reminder — lists issues waiting on an approver. Runs daily at 07:00 UTC.

Linear access is read-only; Slack is the only writer. Adding a workflow is a new file plus one registry line and one cron — the scheduler, data layer, and Slack delivery never change. Its architecture, workflows, and per-app setup live in apps/horns/linear-reports/README.md.

Deploying

Each app deploys on its own with wrangler, run from its own directory. The standard procedure — an app’s README fills in the specifics (binding names, the secret list, rollout order):

  1. Authenticate — wrangler login (or export CLOUDFLARE_API_TOKEN). One-time per machine, run by the deployer.
  2. Provision state — create any KV/D1/R2 namespaces (wrangler kv namespace create <BINDING>, plus --preview) and paste the returned ids into wrangler.toml.
  3. Set secrets — wrangler secret put <NAME> for each key or token. Never commit them.
  4. Validate dry-run first — exercise the app with side effects gated off (DRY_RUN="1") and read the output before enabling anything.
  5. Deploy — wrangler deploy (or the app’s pnpm deploy). A scheduled app registers its cron triggers on deploy; the schedule stays dormant until then.
  6. Go live deliberately — flip the gate (DRY_RUN="0") and redeploy, enabling one trigger at a time while watching wrangler tail.
  7. Rollback — re-gate (DRY_RUN="1") or drop the crons and redeploy, or wrangler rollback to the previous version.

The repo-level guideline lives in apps/horns/README.md; each app documents its concrete bindings, secrets, and rollout order in its own README.

Conventions

  • One directory per app, fully self-contained (its own wrangler.toml, package.json, lockfile).
  • No shared package until a second app needs to reuse code (for example the Linear/Slack clients) — extract a packages/ workspace then, not before.
  • Ship gated off. Side effects default to disabled so a deploy is safe; turning them on is an explicit, observable step.
  • Secrets in wrangler secret, never in wrangler.toml.