Issue 16

.env.local.example

@@ -1,3 +1,12 @@
-# create local copy of this file and rename to .env.local
-# make sure to add .env.local to .gitignore!!
-MONGO_URI={mongo-uri-here}
+# Copy to .env.local and replace the entire placeholder privately.
+# Use the Atlas-generated URI with your explicitly assigned developer database.
+# Dashboard login and database credentials are separate. Never commit credentials.
+MONGO_URI={mongo-uri-with-explicit-developer-database-here}
+
+# Private team management access. Use a unique password of at least 16 characters.
+# These variables are server-only. Never use a NEXT_PUBLIC_ prefix.
+MANAGEMENT_USERNAME=team
+MANAGEMENT_PASSWORD={replace-with-a-long-random-password}
+
+# Optional deliberate live smoke test. Use HTTPS remotely, loopback HTTP locally.
+# LIVE_BASE_URL=https://your-verified-deployment.vercel.app

.github/pull_request_template.md

@@ -2,27 +2,37 @@
 
 Closes #{ISSUE NUMBER HERE}
 
+<!-- `Closes #n` links and auto-closes the issue only when this pull request targets `main`. One issue per pull request. -->
+
 ### Pull Request Summary
 
-{Describe the purpose of your pull request}
+{What this change does, in a sentence a classmate can review}
 
 ### Modifications
 
-{list out the files created/modified and a brief description of what was changed}
+For each file, name the file, the URL it serves (if any), and the mechanism: page, layout, component, CSS Module, or `connectDB`.
+
+- `{path}` — `{URL or none}` — `{mechanism}`: {what changed}
 
 ### Testing Considerations
 
-{list out what you have tested and what the reviewer should verify}
+{What you tried in the browser or with a command, and what the reviewer should verify}
+
+If the `test` script in `package.json` is still a placeholder, say that here. Add a test runner when the issue asks for tests.
+
+### Briefly State What You Learned
+
+{What programming languages, interpersonal skills, or something else you learned or improved from this pull request}
 
 ### Pull Request Checklist
 
 - [ ] Code is neat, readable, and works
 - [ ] Comments are appropriate
-- [ ] The commit messages follows our [guidelines](https://h4i.notion.site/Conventional-Commits-593452ad1179489399ad3bd696ef772a)
+- [ ] Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) (`type(scope): description`). Course notes: [Hack4Impact guide](https://h4i.notion.site/Conventional-Commits-593452ad1179489399ad3bd696ef772a). That spec shapes commit messages, not this pull request body.
 - [ ] The developer name is specified
 - [ ] The summary is completed
-- [ ] Assign reviewers
+- [ ] Reviewers are @mentioned
 
 ### Screenshots/Screencast
 
-{put screenshots of your change, or even better a screencast displaying the functionality}
+{Screenshot or short recording when the change is visible in the browser}

.github/workflows/ci.yml

@@ -20,7 +20,7 @@ jobs:
     # Use matrix strategy to test multiple Node.js versions
     strategy:
       matrix:
-        node-version: [18.x, 20.x, 22.x]
+        node-version: [24.x]
         # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
 
     # Steps represent a sequence of tasks that will be executed as part of the job
@@ -34,15 +34,20 @@ jobs:
           node-version: ${{ matrix.node-version }}
 
       - name: Install dependencies
-        run: npm install
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Check types
+        run: npm run typecheck
 
-      - name: Dry-run build
-        run: npm run build
-        env:
-          # These env variables must be set in the repository's secrets
-          # - Settings -> Secrets and variables -> New repository secret
-          MONGO_URI: ${{ secrets.MONGO_URI }}
-          # Add additional environment variables here
-
       - name: Run tests
         run: npm test
+
+      - name: Build without Atlas credentials
+        run: npm run build
+        env:
+          MONGO_URI: ""
+          MANAGEMENT_USERNAME: ""
+          MANAGEMENT_PASSWORD: ""

.gitignore

@@ -7,9 +7,11 @@
 
 # testing
 /coverage
+/.vitest/
 
 # next.js
 /.next/
+/.next-http-test/
 /out/
 
 # production
@@ -25,7 +27,9 @@ yarn-debug.log*
 yarn-error.log*
 
 # local env files
-.env*.local
+.env
+.env.*
+!.env.local.example
 
 # vercel
 .vercel

.nvmrc

@@ -0,0 +1 @@
+24

AGENTS.md

@@ -0,0 +1,42 @@
+# Coffee Shop agents
+
+Contract for coding agents in this repository. Learning developers can read it to see how an agent is supposed to work here.
+
+Product scope lives in `README.md`. Setup, the folder map, and pull-request steps live in `docs/`.
+
+## Change the app
+
+Reviewers are learning TypeScript, React, Next.js, and Git. Several are coming from Java, Python, or HTML and CSS.
+
+1. Fetch the assigned GitHub issue and restate its acceptance criteria. Done when you can point at the slice you will build.
+2. Implement that slice. The planned features in `README.md` are the product boundary. Done when the diff satisfies the issue and adds nothing the issue left out.
+3. Explain the change for a classmate. Done when the pull request names each file, the URL it serves, and the mechanism: page, layout, component, CSS Module, or `connectDB`.
+
+## Repo rules
+
+- Add a shop page as `src/app/<segment>/page.tsx`. `src/app/layout.tsx` already renders the navbar on every page.
+- The navbar already links to `/`, `/about`, `/menu`, `/specials`, and `/contact`. Add the matching `page.tsx` when that route's issue is the one in progress.
+- Keep `src/app/example`, `src/app/api/example`, and `src/database/userSchema.ts` as starter references until an issue replaces them. `userSchema.ts` is an example user model, separate from menu data.
+- Call `connectDB` in `src/database/db.ts` only from code that reads or writes MongoDB. It reads `MONGO_URI`. The home page stays runnable without that variable.
+- Style with `src/app/globals.css` or a CSS Module in `src/styles/`. Import application code with the `@/` alias, which points at `src/`.
+- Check the `test` script in `package.json` before claiming tests ran. Add a test runner when the issue asks for tests.
+
+## Reach these docs
+
+- **Setup, languages, and wiring** — `docs/getting-started.md` when you explain the tree, a language, or how a `page.tsx` becomes a URL, or when a teammate is installing the app.
+- **Branches and pull requests** — `docs/contributing.md` when you branch, commit, or open a pull request. One issue, one branch, into `main`.
+- **Tools already here** — `docs/project-setup.md` when asked what is already configured.
+- **Workflow skills** — the matching file under `skills/` when the task is grilling, a spec, tickets, test-first implementation, or triage.
+- **Issue tracker** — `docs/agents/issue-tracker.md` when you publish a spec, fetch a ticket, or edit an issue. The tracker is GitHub Issues for `BrianLiDesign/coffee-shop`.
+- **Triage labels** — `docs/agents/triage-labels.md` when a skill names a triage role. Apply this repo's label for that role.
+- **Domain language** — `docs/agents/domain.md` when you name a shop concept in an issue, test, or refactor, or when a change would contradict a recorded decision. Glossary: root `CONTEXT.md`. Decisions: `docs/adr/`.
+
+<!-- BEGIN:nextjs-agent-rules -->
+
+## This is NOT the Next.js you know
+
+This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.
+
+This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.
+
+<!-- END:nextjs-agent-rules -->

CONTEXT.md

@@ -0,0 +1,20 @@
+# Coffee Shop
+
+The shop presents its offerings to customers and lets the team maintain the menu.
+
+## Language
+
+**Offering**:
+A drink or food item available from the shop, with a name, description, price, and category.
+_Avoid_: Product, menu record
+
+**Special offering**:
+An offering the shop currently features on its Specials page. Being featured does not necessarily imply a reduced price.
+_Avoid_: Discount, sale item
+
+**Menu**:
+The collection of offerings customers can browse.
+
+**Offering management**:
+The team's activity of maintaining offerings shown to customers.
+_Avoid_: Customer ordering

README.md

@@ -1,32 +1,74 @@
-# name of non-profit
+# Coffee Shop
 
-{One sentence description of the project}
+A student-built coffee shop site. Customers browse stored offerings and specials, read the shop story, and find contact information. Authorized team members can create, edit, and delete offerings through the management page.
 
-## Table of Contents
+**Existing public site:** [Coffee Shop on Vercel](https://coffee-shop-sigma-rouge.vercel.app/). The Milestone 3 foundation is integrated through PR #31; production deployment, database configuration, and live operation verification must be verified separately. The [Milestone 3 preview](https://coffee-shop-git-feat-milestone-3-release-brianlidesign.vercel.app/) has Vercel sign-in protection. See the [deployment guide](docs/milestone-3-deployment.md) and [release evidence](docs/milestone-3-evidence.md). A successful local build is not live deployment evidence.
 
-- [Overview](#overview)
-  - [Purpose](#purpose)
-  - [Team](#team)
-- [Getting Started And Contributing](#getting-started-and-contributing)
+## Features
 
-## Overview
+- Public pages: Home (`/`), About (`/about`), Menu (`/menu`), Specials (`/specials`), and Contact (`/contact`).
+- Menu and Specials read MongoDB through `/api/offerings`; Specials uses the saved boolean flag.
+- Protected management at `/manage-offerings`: creation, editing, delete confirmation, validation, and pending/success/error feedback.
+- Loading, empty, error, and retry states, with responsive layouts.
+- Repeatable insert-only seeding of the 16 starting offerings, including three specials.
+- Vitest unit/component tests plus real HTTP and disposable database regression tests.
 
-### Purpose
+Create/read are the required Milestone 3 operations. Update/delete are Brian's additional assignment. Customer orders, payments, drink customization, and delivery integrations remain future work. Starter examples at `/example` and `/api/example` are learning references.
 
-{Short paragraph description of the non-profit mission and the purpose of this project. Who will this project help, why is it necessary. Impact of the project.}
+## Tech stack
 
-### Team
+Next.js 16 App Router, React 19, TypeScript, CSS Modules, MongoDB Atlas, Mongoose 8, Vitest 5, React Testing Library, ESLint, Prettier, and Vercel. Use **Node.js 24.x** and npm, matching CI and the deployment runtime.
 
-The {non-profit name} team consists of {#} Cal Poly students. Over the course of about 9 months, we worked as a team to deploy this web application. The team members are listed below:
+## Local setup
 
-- [First Last](https://www.linkedin.com/) - Project Manager
-- [First Last](https://www.linkedin.com/) - Designer
-- [First Last](https://www.linkedin.com/) - Tech Lead
-- [First Last](https://www.linkedin.com/) - Tech Lead
-- [First Last](https://www.linkedin.com/) - Software Developer
+1. Clone the repository and open its root directory.
+2. Install Node.js 24.x, then run `npm ci`.
+3. Copy `.env.local.example` to the ignored `.env.local`.
+4. Privately replace the MongoDB placeholder with a URI containing your assigned database name. Set your management username and a unique password of at least 16 characters.
+5. Run `npm run db:check` to verify real read access.
+6. To deliberately seed this database, run `npm run db:seed -- --apply`. Reruns insert missing seed records and preserve existing records and edits.
+7. Run `npm run dev` and open [localhost:3000](http://localhost:3000).
+8. Open [management](http://localhost:3000/manage-offerings) and sign in through the browser's credential prompt.
 
-## Getting Started And Contributing
+The home page runs without MongoDB. Database pages show a readable error when configuration or connectivity is unavailable; there is no sample-data fallback. Do not share populated environment files or screenshots of credentials.
 
-Visit [getting-started.md](docs/getting-started.md) on info for how to set up this repo.
+## Environment variables
 
-Visit [contributing.md](docs/contributing.md) on info for how to contribute to this repo.
+| Variable              | Purpose                                                                                       |
+| --------------------- | --------------------------------------------------------------------------------------------- |
+| `MONGO_URI`           | Server-side MongoDB connection string with an explicit shop database                          |
+| `MANAGEMENT_USERNAME` | Private team management username; must not contain a colon                                    |
+| `MANAGEMENT_PASSWORD` | Private management password, at least 16 characters; placeholder values are rejected          |
+| `LIVE_BASE_URL`       | Optional HTTPS origin for deliberate live acceptance checks; loopback HTTP is allowed locally |
+
+Configure these privately in Vercel for the relevant environment. Never hardcode credentials or use a `NEXT_PUBLIC_` prefix for them. Keep preview and production database targets separate.
+
+## Tests and quality checks
+
+- `npm run test:unit` runs Vitest once; `npm run test:watch` runs it interactively.
+- `npm run test:regression` checks real HTTP persistence, seeding, database access tooling, and existing frontend behavior.
+- `npm test` runs both suites.
+- `npm run preflight` runs lint, typecheck, all tests, and a production build.
+- `npm run db:check:write` deliberately verifies write/read/cleanup using its own disposable marker.
+- `npm run test:live` reads the explicitly configured live target without writing.
+- `npm run test:live -- --confirm-writes` verifies live create/read and cleans up only its disposable offering.
+- `npm run test:live -- --confirm-writes --all` also verifies updates. Cleanup verifies deletion.
+
+Automated persistence checks start disposable loopback MongoDB instances and require no Atlas credentials. The first run may download MongoDB 7.0.24. Each developer must personally contribute and explain at least three relevant Vitest cases; the shared suite does not establish individual completion.
+
+## Deployment
+
+Follow the [Vercel release guide](docs/milestone-3-deployment.md). Keep customer pages public and management protected. Verify live persistence, responsive behavior, and failure states before replacing the pending live URL above.
+
+## Team and workflow
+
+After PR #31 merges, developers can start from updated `main`, including Sofie's
+acceptance safeguards in issue #36. Vedika's customer-page test foundation was
+already available before that merge. The [test handoff](tests/unit/README.md)
+identifies her starter file and three assigned Vitest cases. Preserve submitted
+contributions and record personal evidence in
+[`docs/milestone-3-evidence.md`](docs/milestone-3-evidence.md).
+
+Brian: tech lead, integration, access control, deployment, documentation, update/delete. Jean: backend handlers. Naomi: database and seeding. Vedika: customer frontend. Aditi: management frontend. Sofie: acceptance tooling and release evidence.
+
+See the [Milestone 3 plan](docs/milestone-3-plan.md) for assignments, acceptance criteria, and the release checklist. Follow [Contributing](docs/contributing.md): one issue, one branch, one reviewed PR into main. Learning developers can start with [Getting started](docs/getting-started.md); agents follow [AGENTS.md](AGENTS.md).

docs/adr/003-public-offering-management.md

@@ -0,0 +1,11 @@
+# Public offering management for Milestone 3
+
+Status: accepted for the implementation branch on October 7, 2026.
+
+Brian approved implementing the Milestone 3 plan, including controlled management access and additional update/delete operations. This supersedes Milestone 2's local-only write restriction for this release.
+
+Customer pages and GET offerings are public. Management uses private HTTP Basic team credentials over HTTPS in deployment. Proxy provides the browser challenge, while the server page and each write handler independently enforce access. Missing or placeholder configuration denies access. Browser writes from another origin are rejected. Secrets are read only on the server.
+
+This student release intentionally has no individual accounts, roles, session database, or password recovery. Browsers cache Basic credentials; ending the browsing session is the practical sign-out mechanism. Individual staff access is a separate future design.
+
+Brian also approved a supported framework upgrade after the production dependency audit found critical vulnerabilities in Next.js 14. The release uses Next.js 16, React 19, Node.js 24, ESLint flat configuration, asynchronous request APIs, and `proxy.ts`. The plan and deployment guide record verification and release boundaries.

docs/agents/domain.md

@@ -0,0 +1,12 @@
+# Domain Docs
+
+This is a single-context repository. Engineering skills should consult the following files when they exist:
+
+- `CONTEXT.md` at the repository root.
+- Relevant decisions in `docs/adr/`.
+
+If these files do not exist, proceed without flagging their absence. The domain-modeling flow creates them lazily when terms or decisions need to be recorded.
+
+Use the glossary vocabulary from `CONTEXT.md` when naming domain concepts in issues, proposals, refactors, and tests. If a needed concept is not defined, note the gap rather than silently introducing competing terminology.
+
+If an implementation or proposal contradicts an existing ADR, surface the conflict explicitly rather than silently overriding it.

docs/agents/issue-tracker.md

@@ -0,0 +1,26 @@
+# Issue tracker: GitHub
+
+Issues and specs for this repo live as GitHub issues in `BrianLiDesign/coffee-shop`. Use the `gh` CLI for issue operations.
+
+## Conventions
+
+- Create an issue with `gh issue create --title "..." --body "..."`.
+- Read an issue with `gh issue view <number> --comments`.
+- List issues with `gh issue list --state open` and add label or JSON filters as needed.
+- Comment on an issue with `gh issue comment <number> --body "..."`.
+- Apply or remove labels with `gh issue edit <number> --add-label "..."` or `--remove-label "..."`.
+- Close an issue with `gh issue close <number> --comment "..."`.
+
+Infer the repository from the GitHub remote; `gh` does this automatically from the repository checkout.
+
+## Pull requests as a triage surface
+
+**PRs as a request surface: no.** External pull requests are not included in the triage queue by default.
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitHub issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `gh issue view <number> --comments`.

docs/agents/triage-labels.md

@@ -0,0 +1,13 @@
+# Triage Labels
+
+The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
+
+| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
+| -------------------------- | -------------------- | ---------------------------------------- |
+| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
+| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
+| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
+| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
+| `wontfix`                  | `wontfix`            | Will not be actioned                     |
+
+When a skill mentions a role, use the corresponding label string from this table.