A small single-page web app that estimates how many meal blocks and FLEX dollars a Carnegie Mellon student should have consumed by a given date — and how many should remain — based on their dining plan and time spent on campus.

The tool spreads a plan's totals evenly across the days you're expected to be on campus, then reports three views of that budget: a per-week rate, an amount consumed so far, and an estimated remaining balance, for both meal blocks and FLEX.

Estimates are informational and based on even distribution across on-campus days. They are not official dining balances.

Features

Pick from all eight dining plans (Green, Blue, Red, Yellow, Tartan Flex, Scotty's Choice, Whitfield's Favor, Piper Select).
"As of" date picker that defaults to today and is clamped to the meal period.
Checkboxes for configured breaks ("missing periods") you spent off campus.
A numeric input for any additional days you don't want counted.
Live-updating results — every input recomputes the estimate instantly.
Everything is config-driven: plans, dates, and breaks live in one JSON file that is fetched at runtime. Edit it on the server and changes appear on the next page load — no rebuild needed.
Your plan, checked breaks, and extra-days value are remembered between visits (via localStorage). The date always resets to today.
Dark theme with restrained CMU Tartan-red accents.
Ships as plain static files — no server-side code or backend.

Getting started

Requires Node.js 18+.

npm install      # install dependencies
npm run dev      # start the dev server at http://localhost:5173

Other scripts

npm run build    # type-check, build to dist/, then inject the Discord embed
npm run embed    # (re)inject the Discord embed into an existing dist/ build
npm run preview  # serve the production build locally
npm test         # run the estimation-engine tests

Configuration

All tunable values live in public/config.json. This file is fetched at runtime, not compiled into the bundle — so after deployment you can edit the deployed config.json directly and the changes take effect on the next page load, with no rebuild.

During development, edit public/config.json and reload the page.

{
  "mealStartDate": "2026-08-24",   // first day of the meal period (YYYY-MM-DD)
  "mealEndDate": "2026-12-13",     // last day of the meal period (YYYY-MM-DD)

  "plans": [
    {
      "id": "green",               // stable unique key
      "displayName": "Green",      // shown in the dropdown
      "totalMealBlocks": 210,      // total blocks for the whole meal period
      "totalFlexDollars": 500      // total FLEX dollars for the whole meal period
    }
    // ...more plans
  ],

  "missingPeriods": [
    {
      "id": "fall-break",          // stable unique key
      "displayName": "Fall Break", // shown next to the checkbox
      "startDate": "2026-10-19",   // inclusive
      "endDate": "2026-10-20"      // inclusive
    }
    // ...add as many as you like; each becomes a checkbox
  ]
}

Notes:

The shipped plan numbers are placeholders. Replace totalMealBlocks and totalFlexDollars with the real figures from your CMU dining agreement, and set the correct mealStartDate / mealEndDate for your semester.
Add or remove plans and missing periods freely. Every missing period automatically becomes a checkbox in the UI.
If the config is malformed (missing fields, bad dates, duplicate ids, negative totals), the app shows a readable list of problems instead of rendering broken estimates.

How the estimate works

Total active days = every calendar day in [mealStartDate, mealEndDate], minus the days covered by any break you check.
Daily rate = plan total / total active days, computed separately for blocks and FLEX.
Active days consumed = active days from the start up to your "as of" date, minus checked breaks in that window, minus any additional excluded days.
Consumed = daily rate × active days consumed.
Remaining = plan total − consumed.
Per week = daily rate × 7.

Checking a break or adding excluded days shifts your expected consumption down, which is what you want when you were away and not eating on campus.

Deployment (static hosting)

The app is a purely client-side static site — no backend, no server-side rendering. To deploy:

npm run build      # outputs everything to dist/

Then copy the contents of dist/ to wherever you're serving from. The build produces:

dist/
  index.html
  config.json      # the live, editable config
  assets/          # hashed JS + CSS

Subpath hosting

Asset paths in the build are relative, and config.json is loaded relative to the page's own location. That means the app works unchanged whether it's served from a domain root or a subpath — e.g. https://www.cmu.edu/~you/meal-estimator/. No base-path configuration or rebuild is needed to move it between locations.

The one requirement is that the app is served as a directory with a trailing slash (e.g. .../meal-estimator/). Virtually all static servers (Apache, nginx, and the like) redirect .../meal-estimator to .../meal-estimator/ automatically, so this is handled for you.

Editing config after deployment

Because config.json sits alongside index.html in the deployed files and is fetched at runtime, you can update plan numbers, dates, or breaks by editing the deployed config.json directly. No rebuild or redeploy of the JS is required — just reload the page.

Discord link embed

The page's <head> includes a Discord Components V2 link embed (<script id="discord:component-embed" type="application/json">). When the site URL is pasted into Discord, its crawler reads that JSON and renders a rich card showing the site name, a short blurb, the site icon, and the Red plan's on-pace estimate for the current day (blocks left, FLEX left, suggested weekly pace).

Because Discord's crawler reads the static HTML and does not run the page's JavaScript, this data is baked in at build time by scripts/inject-embed.mjs. That script uses the same estimation engine the app uses, so the embed and the app always agree. Two consequences worth knowing:

The embed is a snapshot from the moment of the build — it does not update on its own. The nightly deploy (below) rebuilds it so it stays current.
It cannot show per-user results, since those only exist after the JS runs in a real browser.

SITE_ICON_URL controls the absolute icon URL Discord fetches; the deploy workflow sets it from SITE_BASE_URL.

Automated nightly deployment (Gitea Actions)

.gitea/workflows/deploy.yml rebuilds the site every night (refreshing the embed snapshot), uploads dist/ to CMU AFS space over SFTP, and then triggers CMU's publish CGI to make the files live. It also runs on pushes to main and can be triggered manually from the Gitea Actions UI.

Why an on-campus runner is required

linux.andrew.cmu.edu (the SFTP target) is only reachable from inside CMU's network. A cloud/hosted Gitea runner sits on the public internet and cannot reach it, which is what causes lftp to fail with max-retries exceeded. The workflow is therefore pinned to a self-hosted runner via runs-on: cmu-onsite; only a runner registered with that label — running on a machine inside CMU's network — will pick up the job.

Setting up the `cmu-onsite` runner

Run act_runner on a machine that stays on CMU's network. Register it against this repo (or your Gitea instance) with the cmu-onsite label mapped to a Node-capable Docker image, so the workflow's apt-get/Node steps work unchanged:

# On the on-campus machine (Docker installed and running):
act_runner register \
  --instance https://your-gitea-host \
  --token <REGISTRATION_TOKEN_FROM_GITEA> \
  --name cmu-onsite-01 \
  --labels 'cmu-onsite:docker://node:20-bookworm' \
  --no-interactive

# Then run it (or install as a service):
act_runner daemon

Notes:

The registration token comes from Gitea under Settings → Actions → Runners → Create new runner (repo-level) or the equivalent org/site-level page.
The :docker://node:20-bookworm suffix is what makes the label run jobs in a Debian container with Node preinstalled. Without an image mapping the label would run directly on the host, and the sudo apt-get install lftp step would need the tools present on the machine instead.
Confirm the runner host can actually reach the target before relying on it: nc -vz linux.andrew.cmu.edu 22. Some CMU subnets are firewalled off from the timeshare hosts.
Keep the runner process up (systemd service, container restart policy, etc.) so the nightly schedule fires.

Required secrets

Set these in your Gitea repo under Settings → Actions → Secrets:

Secret	Required	Description
`SFTP_HOST`	yes	SFTP server hostname (e.g. `unix.andrew.cmu.edu`).
`SFTP_USERNAME`	yes	Your Andrew (AFS) username. Also used for the publish callback.
`SFTP_PASSWORD`	yes	Password for the SFTP account.
`SFTP_REMOTE_PATH`	yes	Absolute remote directory to upload into (e.g. `/afs/andrew.cmu.edu/usr/<user>/www/meal-estimator`).
`SITE_BASE_URL`	yes	Public base URL of the site (e.g. `https://www.andrew.cmu.edu/user/<user>`). Used to build the embed icon URL. No trailing slash.
`SFTP_PORT`	no	SFTP port; defaults to `22` if unset.

What the workflow does

Checks out the repo and installs dependencies with npm ci.
Runs npm run build, which type-checks, bundles, and injects the current day's Red-plan embed (with SITE_ICON_URL derived from SITE_BASE_URL).
Uploads dist/ to SFTP_REMOTE_PATH using lftp mirror -R --delete (the remote is mirrored to match the build; files no longer present locally are removed).
Calls https://www.andrew.cmu.edu/cgi-bin/publish?FLAG=0&NAME=<SFTP_USERNAME> to publish. The step fails loudly if the publish request returns an HTTP error.

Scheduling note

The cron in the workflow is in UTC. It is set to 0 5 * * *, which is midnight US Eastern during EST. For EDT (daylight saving), use 0 4 * * *. Adjust to taste, or keep both in mind when the clocks change.

Security notes

The SFTP password is passed to lftp via an environment variable interpolated into the command; keep it only in Gitea secrets, never in the repo.
Host-key checking is disabled on the runner (via StrictHostKeyChecking=no in the SSH connect-program) because CMU's host key is not pre-seeded there. The transfer is still encrypted, but this does not verify the server's identity. If you want strict host-key verification, add the server's key to the runner's known_hosts and remove that option.
The upload step runs lftp with debug 3 and forces password auth over an explicit ssh connect-program. This makes connection failures visible in the job log and re-enables a few older key-exchange / host-key algorithms that some CMU hosts still require.

Data persistence

The selected plan, checked breaks, and additional-days value are saved to the browser's localStorage and restored on the next visit. The "as of" date is intentionally not persisted — it always defaults to today. Persistence fails silently if localStorage is unavailable (e.g. private browsing), and stale entries (a plan or break no longer in the config) are ignored on load.

Project structure

index.html            # app shell (includes the Discord embed placeholder)
public/
  config.json         # all tunable values (plans, dates, breaks); served + fetched at runtime
  favicon.svg         # site icon (fork + progress arc)
src/
  types.ts            # shared types
  dates.ts            # whole-day date helpers
  configLoader.ts     # validates + normalizes config
  configFetch.ts      # fetches config.json at runtime (subpath-aware)
  engine.ts           # pure estimation math (no DOM)
  store.ts            # tiny reactive state store
  persistence.ts      # localStorage load/save of selections
  main.ts             # builds the UI, re-renders on change
  style.css           # dark CMU-accented theme
  engine.test.ts      # engine unit tests
  sanity.test.ts      # checks against the shipped config
scripts/
  inject-embed.mjs    # build-time: injects today's Red-plan Discord embed into dist/
.gitea/workflows/
  deploy.yml          # nightly build + SFTP deploy + CMU publish

Tech stack

Vite for dev server and bundling
TypeScript (strict mode)
Vitest for tests
No UI framework — plain DOM with a small reactive store

Tests

The estimation engine is a set of pure functions, kept separate from the DOM so it can be tested directly:

npm test

Covers day counting across boundaries, budget conservation, monotonicity when excluding days, the zero-active-days (division-by-zero) edge case, and sanity checks against the shipped config.

README.md Unescape Escape

CMU Meal Estimator