Maintenance Playbook

Use this guide to keep the Ethotechnics site healthy with minimal guesswork. It covers recurring checklists, dependency hygiene, and fast resets when local builds get noisy.

Quick health check (10 minutes)

  1. Ensure dependencies are installed: bun install
  2. Validate code quality: bun run lint
  3. Run the default tests (prepares builds once): bun run test
  4. Optional UI coverage when navigation or forms change: bun run test:e2e

A clean working tree after these commands confirms generated files remain ignored.

Recurring cadence

  • Weekly:
    • Run bun run verify to mirror CI (check:node-modules → lint → prepare builds once → unit/worker + content).
    • Check for outdated packages with bun outdated and plan updates.
    • Run bun run build to refresh the sitemap if content or the site config changed.
  • Before releases or campaigns:
    • Execute the full E2E suite: bun run test:e2e.
    • Run a fresh build and spot-check navigation labels after content updates.
    • Preview locally with bun run dev and scan key flows (navigation, forms, library feed).

Dependency update runbook

  1. Inspect versions with bun outdated to prioritize security and bugfix bumps.
  2. Update in small batches (patch/minor first): 
    bun add <package>@latest
# or for specific majors
bun add <package>@<version>
  3. Rebuild and retest with the CI-equivalent path:
    • bun run verify
  4. For build-tooling upgrades (e.g., esbuild, Lightning CSS), rerun bun run test:e2e if you need a targeted E2E check after verification.
  5. Capture upgrade notes in commit messages so future maintainers know why versions changed.

Content and sitemap hygiene

  • Run bun run build after editing templates, partials, the site config, or content pages so Astro regenerates app/dist and sitemap.xml.

Fast local resets

  • Clear cached lint results when tooling behaves oddly: 
    rm -f .eslintcache .stylelintcache
  • Remove generated assets to force a clean rebuild (leave templates and partials intact): 
    rm -f app/dist/assets/*.css index.html tags/*/index.html app/dist/sitemap.xml
bun run build
  • If Wrangler dev ports collide, set a new port temporarily: 
    PORT=8799 bun run dev

Runtime and Worker checks

  • Validate Worker behavior with the smoke tests: bun run test:unit (covers both worker handlers and site-level checks).
  • When adjusting request handlers or routes, dry-run the Worker locally via bun run dev and exercise the affected endpoints with curl or a browser.

Sticking to these habits keeps the static build, Worker, and content pipelines predictable—and makes future changes easier to land.