studio-os 0.2.0

package/.dockerignore

@@ -0,0 +1,7 @@
+node_modules
+data
+.git
+.env
+test
+*.log
+PROGRESS.md

package/.env.example

@@ -0,0 +1,34 @@
+# Studio OS configuration. Copy to .env and edit. Everything is optional;
+# the app runs fully offline with no env at all.
+
+# Port for the HTTP server (default 3000)
+#PORT=3000
+
+# Path to the SQLite database (default data/studio.db)
+#DB_PATH=data/studio.db
+
+# Secret used to sign session cookies and magic-link tokens.
+# Auto-generated and persisted in the settings table on first boot if unset.
+#APP_SECRET=change-me
+
+# Public base URL used in emails/magic links (default http://localhost:PORT)
+#BASE_URL=https://booking.example.com
+
+# Set when running behind a reverse proxy (Caddy/nginx/Traefik) so rate
+# limiting keys on the first X-Forwarded-For hop. Leave unset otherwise —
+# the header is client-spoofable without a trusted proxy in front.
+#TRUST_PROXY=1
+
+# --- SMTP (optional). When unset, emails are written to data/outbox/*.eml
+# and magic links are shown on screen.
+#SMTP_HOST=smtp.example.com
+#SMTP_PORT=587
+#SMTP_USER=user
+#SMTP_PASS=pass
+#SMTP_FROM="My Studio <noreply@example.com>"
+
+# --- Stripe (optional, bring-your-own account). When unset, purchase flows
+# fall back to "pay at studio" and manual activation.
+#STRIPE_SECRET_KEY=sk_test_...
+#STRIPE_WEBHOOK_SECRET=whsec_...
+#STRIPE_PUBLISHABLE_KEY=pk_test_...

package/CHANGELOG.md

@@ -0,0 +1,86 @@
+# Changelog
+
+## 0.2.0 — 2026-07-28
+
+- **Instructor logins.** New `instructor` user role alongside the existing
+  owner/staff (admin) roles — existing accounts are untouched by the
+  migration (v2 rebuilds the `users` CHECK; SQLite cannot alter one in
+  place). Instructors sign in on the same staff login form (`/login` now
+  aliases `/admin/login`) and land on their own portal:
+  - `GET /instructor/schedule` — the classes they are assigned to, from
+    today onward, sorted by date
+  - `GET /instructor/classes/:id/roster` — attendee list with status
+    (booked / checked-in / no-show / cancelled), class time and capacity;
+    client emails are *not* exposed to instructors
+  - `POST /instructor/classes/:id/checkin/:booking_id` — check an attendee
+    in (same `markAttendance` business logic as the admin roster)
+  - Route guards: every `/admin/*` route returns **403** for instructor
+    accounts; rosters and check-in return **403** for classes the
+    instructor is not assigned to.
+- **Admin: instructor account management.** The Instructors page gains an
+  "Instructor logins" section; `/admin/instructors/new` creates an account
+  (name, email, password ≥ 8 chars, role `instructor`);
+  `/admin/instructors/:id/classes` assigns/unassigns upcoming classes via
+  checkboxes (many-to-many `instructor_class_assignments` table, cascade
+  on account/instance deletion; past assignments are left untouched).
+- 12 new tests (guards, scoping, check-in, admin CRUD, migration; the four
+  new views covered by the integrity suite) — 110 total, no network.
+  Upgrade path verified against a real v1 database file.
+
+## 0.1.0-hardening — 2026-07-28
+
+- **Fix: CSRF inputs injected inside attribute values.** The hardening pass had
+  inserted the hidden `_csrf` input at the wrong offset in 22 forms whose
+  `action` contained an EJS expression, corrupting the submit URL and leaking
+  markup as visible text. All POST forms now carry the token immediately after
+  the form open tag, enforced by a new static views-integrity test suite
+  (`test/views.test.js`), and verified with a real in-browser form submission.
+- **README screenshots**: 8 captured views of the seeded demo studio (public
+  schedule/booking/buy, admin dashboard/schedule/roster/client/reports).
+- **Docker verified end-to-end**: `docker compose build && up -d` → setup
+  wizard, admin class creation, public schedule and a guest booking all
+  exercised against the running container, then `down -v`. Fixed
+  `docker-compose.yml`: an `environment:` key with only commented entries is
+  invalid YAML for compose ("must be a mapping") — the example block is now
+  fully commented out.
+- **Rate limiting**: dependency-free in-memory fixed-window limiter
+  (`src/lib/ratelimit.js`), keyed per client IP + route: magic-link requests
+  5/15 min, admin login 10/15 min, public booking/buy POSTs 30/15 min;
+  friendly 429 with `Retry-After`. `X-Forwarded-For` is honored only when
+  `TRUST_PROXY` is set. Single-process counters (reset on restart) — see the
+  new README Security section.
+- **CSRF protection**: session-bound random token (stored in the signed
+  cookie-session, no deprecated `csurf` dependency), hidden `_csrf` input on
+  every state-changing form (public booking/buy/magic-link, client cancel,
+  setup wizard, admin login and all admin forms); POST/PUT/DELETE/PATCH
+  without a valid token → 403. `/webhooks/stripe` exempt (Stripe-signature
+  verified raw body instead). `x-csrf-token` header accepted as an
+  alternative to the form field.
+
+## 0.1.0 — 2026-07-27
+
+First release. Single-studio, self-hosted, bring-your-own Stripe.
+
+- Public schedule (14-day view, filters), class pages, guest booking with
+  waiver capture, returning-client booking by email
+- Booking engine: membership → soonest-expiring pack → drop-in payment
+  resolution; atomic capacity; FIFO waitlist with auto-promotion;
+  cancellation-window refunds; late-cancel forfeit/refund policy; attendance
+- Client self-service via HMAC magic links (no client passwords): view
+  upcoming bookings, cancel within policy
+- Rolling 8-week schedule materialization from weekly rules (boot + daily +
+  on change), one-off classes, class cancellation with notify + refund
+- Admin: dashboard (today's rosters, week revenue, expiring passes), class
+  types / instructors / weekly rules CRUD, roster check-in/no-show/walk-in,
+  client profiles (manual passes, memberships, payments, waiver, magic link),
+  products (packs + membership plans), revenue & attendance reports + CSV,
+  settings, SQLite backup via `VACUUM INTO`
+- Buy page: Stripe Checkout for packs (one-time) and memberships
+  (subscription) with signature-verified, idempotent webhook fulfillment;
+  full manual "pay at studio" fallback when Stripe is unconfigured
+- Email via SMTP, or `data/outbox/*.eml` + on-screen links when unset
+- Mindbody CSV importer (clients + pricing options): CLI + admin page,
+  JSON column mapping with defaults, dry-run, idempotent by email
+- Seed script (`npm run seed`), Dockerfile + docker-compose, PWA manifest +
+  service worker, vendored htmx/Pico.css (no CDN), 67 tests (no network)
+

package/Dockerfile

@@ -0,0 +1,25 @@
+# Studio OS — single-container deployment.
+# better-sqlite3 ships prebuilt binaries for glibc (node:*-slim), so no
+# build toolchain is needed.
+FROM node:22-slim
+
+ENV NODE_ENV=production
+WORKDIR /app
+
+# Install dependencies first for layer caching.
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev
+
+COPY src ./src
+COPY views ./views
+COPY public ./public
+COPY scripts ./scripts
+
+# SQLite database + email outbox live here — mount a volume to persist.
+ENV DB_PATH=/app/data/studio.db
+VOLUME /app/data
+
+ENV PORT=3000
+EXPOSE 3000
+
+CMD ["node", "src/server.js"]

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Studio OS contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PROGRESS.md

@@ -0,0 +1,60 @@
+# Studio OS — build progress
+
+Authoritative spec: `SPEC.md`. Node used: **v22.18.0** (better-sqlite3 11.x prebuilt, SQLite 3.49.2 — no compile needed).
+Run tests: `npm test`. Start: `npm start` (PORT env, default 3000).
+
+## Done
+- [x] Scaffold: package.json (studio-os, MIT, type:module), deps installed, htmx 1.9.12 + pico.css 2.0.6 vendored in `public/vendor/` (commit 2cb4364)
+- [x] DB: `src/db/schema.sql` (migration v1), `src/db/index.js` (WAL, FK on, migrations, settings helpers, audit), `src/lib/time.js` (Intl-based tz conversion, no tz lib)
+- [x] Core booking engine `src/services/booking.js`: payment resolution (membership → soonest-expiring pack → drop-in), atomic capacity via transactions, waitlist FIFO + promotion (re-resolves payment at promotion), cancellation window refund / late-cancel forfeit (policy setting), cancelClass full refund, attendance marking
+- [x] Rolling schedule generator `src/services/schedule.js` (8-week horizon, idempotent on (rule_id, starts_at))
+- [x] Tests: 31 passing (`test/booking.test.js`, `test/schedule.test.js`) covering every SPEC booking rule incl. capacity race, FIFO promotion, credit deduct/refund, soonest-expiring pack selection, tz materialization (commit fadbc47)
+- [x] Auth service (bcryptjs + HMAC magic-link tokens), mailer (SMTP or `data/outbox/*.eml` fallback + all templates), Stripe service (isolated, injectable client, idempotent fulfillment by `payments.stripe_session_id` UNIQUE)
+- [x] App skeleton `src/app.js` (webhook raw-body mounted before parsers, cookie-session, setup gate, view locals) + `src/server.js` (boot + daily generator)
+- [x] Routes: setup wizard, staff login/logout, webhooks, public (schedule/class/book with waiver/buy/magic-link request), `src/routes/me.js` (magic-link self-service + cancel)
+- [x] Admin routes + full EJS UI (public + admin), PWA assets (manifest, sw.js, custom.css), 16 supertest web tests (commits 897ad8e, 7449c52)
+- [x] Mindbody importer: `src/services/importer.js` (CSV parser, mapping defaults + overrides, idempotent by email), `scripts/import-mindbody.mjs` CLI (--clients/--passes/--mapping/--db/--dry-run), realistic fixtures `test/fixtures/mindbody-{clients,passes}.csv` (edge cases: missing email, quoted commas, uppercase email, malformed row), admin `/admin/import` page wired, 8 importer tests + 1 web test (56 total green)
+
+- [x] Stripe webhook tests `test/stripe.test.js` (11 tests, mock client, no network): signature reject, pack/membership/drop-in fulfillment, replay idempotency, subscription cancel, 500-retry on unknown product, checkout session params (67 total green)
+- [x] `scripts/seed.mjs` (demo studio: 3 instructors, 4 class types, 8 weekly rules → 64 instances, products, 4 clients w/ passes+membership, 2×2 demo bookings; refuses non-empty DB without --force; login owner@example.com/studio-demo), Dockerfile (node:22-slim, VOLUME /app/data) + .dockerignore + docker-compose.yml (studio-data volume), README.md (quickstart Docker+Node, Mindbody migration guide, Stripe guide, limitations, roadmap), CHANGELOG.md. NOTE: docker build not run at the time — verified later, see the hardening pass below.
+
+## Self-verification (2026-07-27, item 8) — ALL PASSED
+Live server on PORT=3791, DB_PATH=data/verify-studio.db (deleted after), Node v22.18.0:
+1. `npm test` → **67/67 pass, 0 fail** (booking 21 + schedule 10 + web 17 + importer 8 + stripe 11).
+2. Fresh empty DB boot: `GET /` → 302 `Location: /setup`; `GET /setup` → 200 "Welcome to Studio OS".
+3. `node scripts/seed.mjs` → 3 instructors, 4 class types, 8 rules → 64 instances, products, 4 clients, 4 demo bookings. Re-run without `--force` correctly refused (exit 1).
+4. Seeded boot: `GET /` → 200; schedule lists 20 upcoming instances (Vinyasa/Pilates/Handstand/Yin) with "spots left".
+5. Booking round-trip: `POST /class/33/book` (new guest, waiver_agree=1) → 200 "Booked"; duplicate re-POST did NOT create a second booking; admin login (`POST /admin/login` → 302) then `GET /admin/instances/33` roster shows the client, paid_with `drop_in_manual` ("pay at studio"), check-in buttons.
+6. Magic-link cancel: `POST /magic-link` → on-screen `/me?token=...` (SMTP off); `GET /me?token` → 200 listing the booking; `POST /me/cancel/5` → 302 back to /me, flash "cancelled", list empty; DB row: status='cancelled', cancelled_at set; roster no longer shows the client.
+7. Server stopped cleanly. NOT verified: `docker build` ($0/no-network guardrail — Dockerfile untested).
+
+## Hardening pass (2026-07-28)
+- [x] CSRF protection: random per-session token stored in the cookie-session, exposed as `res.locals.csrfToken`, hidden `_csrf` input added to all 36 POST forms (public book/buy/magic-link, /me cancel, setup, admin login/logout and every admin form). Middleware in `src/app.js` rejects POST/PUT/DELETE/PATCH with missing/mismatched token (403, timing-safe compare; `x-csrf-token` header also accepted). `/webhooks/stripe` exempt (mounted before the session layer + explicit path guard; authenticated by Stripe signature instead). Tests updated to cookie agents + `csrfToken()` helper; 2 explicit tests (no/wrong token → 403 + nothing written; valid token works; webhook stays exempt). 69/69 green.
+
+- [x] Docker verification (2026-07-28, Docker Desktop 4.44.2 / Engine 28.3.2, linux/amd64): `docker compose build` succeeded first try — `node:22-slim` + better-sqlite3 prebuilt glibc binary, no python3/make/g++ stage needed. Found + fixed a real compose bug: `environment:` list containing only comments parses as null → "must be a mapping" validation error; block now fully commented in mapping form. Live run: `docker compose up -d` → `GET /` 302 `/setup` on fresh volume → completed setup wizard via curl (CSRF cookie+token round-trip) → admin one-off class POST → public schedule renders Yoga Flow → guest booking on `/class/1` → "Booked"; booking POST without CSRF token → 403 in-container. `docker compose down -v` clean. Verified commands recorded in README.
+- [x] Rate limiting: `src/lib/ratelimit.js` (dependency-free in-memory fixed window, key = client IP + matched route pattern, injectable clock, X-Forwarded-For honored only when `TRUST_PROXY` env set). Wired in `src/app.js` before the CSRF check: `/magic-link` 5/15min, `/admin/login` 10/15min, booking/buy POSTs (`/class/:id/book`, `/buy/pack/:id`, `/buy/membership/:id`) 30/15min → friendly 429 + Retry-After. 4 tests in `test/ratelimit.test.js` (trigger, window reset via fake clock — no sleeps, XFF spoof/trust behavior). README limitations updated → new Security section; `TRUST_PROXY` documented in `.env.example`. 73/73 green. NOTE: limiter is per-process and resets on restart (documented).
+
+## v0.2.0 — instructor logins (2026-07-28) — SHIPPED, ALL VERIFIED
+- [x] Migration v2 (`src/db/002-instructor-role.sql`): users role CHECK rebuilt to allow 'instructor' (owner/staff untouched — verified against a real v1 file DB: both users kept, v2 applied, instructor insert OK); new `instructor_class_assignments (instructor_id→users, class_id→class_instances, PK both, ON DELETE CASCADE)` + idx_ica_class.
+- [x] Guards (`src/services/auth.js`): `requireAdmin` (admin router; instructor → 403, anon → 302 login), `requireInstructor` (instructor portal; admins → /admin). Login (`src/routes/auth.js`): `/login` aliases `/admin/login`; POST redirects by role (instructor → /instructor/schedule).
+- [x] Instructor portal (`src/routes/instructor.js` + `views/instructor/{schedule,roster}.ejs`): schedule (assigned classes from studio-local today, sorted by date), roster (attendee + status, 'attended' displayed as 'checked-in'; NO client emails exposed), POST checkin (assignment-guarded, booking must belong to the class, reuses `markAttendance`).
+- [x] Admin UI: Instructors page gains logins section; `/admin/instructors/new` (GET+POST, password ≥8, UNIQUE-email friendly error); `/admin/instructors/:id/classes` checkbox assignment (rewrites only the displayed upcoming window; past assignments kept). Routes declared BEFORE `POST /instructors/:id` so 'new' isn't captured as :id.
+- [x] Tests: `test/instructor.test.js` (8) + 4 new view-integrity tests = **110/110 green** (`npm test`).
+- [x] Live E2E on PORT=3799 (seeded DB, curl, then killed + scratch DB deleted): owner created kim@studio.test, assigned class 25 of 2; instructor login → 302 /instructor/schedule; schedule showed only Mat Pilates #25; /admin → 403; roster #9 → 403; roster #25 → 200; check-in booking 1 → Alice Chan 'checked-in'; check-in on #9 → 403; POST without CSRF → 403.
+- [x] package.json 0.2.0, CHANGELOG 0.2.0 entry, README (feature bullet + walkthrough step 6, roadmap line removed).
+
+## Next
+- v0.2.0 complete. Optional future: docker rebuild sanity check on next release; screenshots of the instructor portal for README.
+
+## Pragmatic choices where SPEC is silent (decided, noted per guardrail)
+- **pack_products table added** (schema v1): SPEC's buy page sells "class packs" but only defines per-client `passes`; a purchasable catalogue was needed. Same for drop-in pending payments → `payments.status` ('paid'|'pending').
+- **Waitlisted bookings do not deduct credits**; deduction happens at promotion (same tx), payment re-resolved at promotion time.
+- **Drop-in online**: booking is created immediately; payment row pending; Stripe checkout (kind=drop_in metadata) marks it paid via webhook. Capacity is not held hostage to checkout completion.
+- **Sessions**: cookie-session (signed cookie) — SPEC allows either. app_secret auto-generated into settings, overridable via APP_SECRET env.
+- ~~No CSRF tokens in v0.1 (same-site=lax cookies); listed in README limitations.~~ Added in the 2026-07-28 hardening pass (session-bound `_csrf` token, no csurf dependency).
+- `npm test` uses glob `"test/*.test.js"` — `node --test test/` breaks under Git Bash path mangling on Windows.
+
+## How to resume
+- `cd D:\Repos\ideas\studio-os && npm test` (expect 31+ green) and `git log --oneline` to see where things stand.
+- Work top-down through “Next”. Commit after each numbered item at minimum.
+- Guardrails: stay inside this folder; $0 / no network at boot or in tests; no remotes/publishing; Stripe/SMTP env-gated.

package/README.md

@@ -0,0 +1,253 @@
+# Studio OS
+
+Self-hosted booking, class-pack and membership management for boutique studios —
+yoga, pilates, martial arts, climbing, dance, small gyms. The Mindbody escape hatch.
+
+**The structural difference no SaaS rival can copy:** payments run on *your own*
+Stripe account. Studio OS never touches the money — no processing markup, no
+per-booking fees, no contracts. Run it in one Docker container or with plain
+Node on a $5 VPS or a spare machine at the studio.
+
+- Public schedule + booking with waiver capture — clients need no passwords
+  (signed magic links for self-service cancellation)
+- Class packs (credits), memberships (unlimited or N/month), drop-ins
+- Atomic capacity, FIFO waitlist with auto-promotion, cancellation-window policy
+- Admin: rosters + check-in, clients, manual sales, revenue/attendance reports + CSV,
+  one-click SQLite backup
+- Instructor logins: per-class assignments, a scoped schedule + roster portal
+  with attendee check-in, zero admin access
+- Mindbody CSV importer (clients + pricing options), idempotent and dry-runnable
+- Stripe Checkout for packs and membership subscriptions (optional), SMTP email
+  (optional — without it, emails land in `data/outbox/` and links show on screen)
+- Everything server-rendered (EJS + HTMX + Pico.css, all vendored — no CDN, no
+  build step, works offline), SQLite in one file, PWA manifest + service worker
+
+## 5-minute quickstart
+
+### Docker
+
+```sh
+git clone <this repo> studio-os && cd studio-os
+docker compose up -d
+# open http://localhost:3000 → setup wizard creates your studio + owner login
+```
+
+The database persists in the `studio-data` volume. Configure SMTP/Stripe by
+uncommenting the `environment:` block in `docker-compose.yml`.
+
+Verified end-to-end (Docker Engine 28.x, linux/amd64, `node:22-slim` base —
+better-sqlite3 uses its prebuilt glibc binary, no compiler stage needed):
+
+```sh
+docker compose build
+docker compose up -d
+curl -i http://localhost:3000/   # 302 → /setup on a fresh volume
+# setup wizard → admin one-off class → public schedule → guest booking: all OK
+docker compose down -v           # stop + remove the data volume
+```
+
+### Bare Node (Node 20+)
+
+```sh
+git clone <this repo> studio-os && cd studio-os
+npm install
+npm start
+# open http://localhost:3000 → setup wizard
+```
+
+The database is a single file at `data/studio.db` (override with `DB_PATH`).
+Copy `.env.example` to `.env` to configure port, SMTP, Stripe. Nothing is
+required — with zero config the app runs fully offline.
+
+Want to look around with data first?
+
+```sh
+npm run seed   # demo studio: classes, weekly schedule, clients, passes
+npm start      # admin login: owner@example.com / studio-demo
+```
+
+### First-run walkthrough
+
+1. Setup wizard: studio name, timezone, currency, owner account.
+2. Admin → Class types: create your classes (duration, capacity, drop-in price, credits).
+3. Admin → Schedule: add weekly rules — instances materialize on a rolling
+   8-week horizon automatically (at boot, daily, and on rule changes).
+4. Share the public schedule (`/`). Clients book with just name + email and sign
+   the waiver on first booking.
+5. Sell packs/memberships from a client's profile (manual), or connect Stripe
+   for online purchase.
+6. Optional: Admin → Instructors → "Add instructor login", then tick the
+   classes they teach. Instructors sign in on the same staff login page and get
+   a portal with just their schedule and rosters (with check-in) — no admin
+   access.
+
+## Migrating from Mindbody
+
+You need two CSV exports from Mindbody:
+
+1. **Clients** — Reports → Clients (or Clients → Export). Standard columns:
+   `First Name, Last Name, Email, Mobile Phone, Notes, Liability Waiver, ...`
+2. **Pricing options** (remaining passes) — Reports → Pricing Options /
+   "Remaining sessions". Standard columns:
+   `Client, Email, Pricing Option, Remaining, Total, Expiration, Price Paid, ...`
+
+Then either paste the CSVs into **Admin → Import** (dry-run checkbox included),
+or run the CLI:
+
+```sh
+# preview first — prints every row's action, writes nothing
+node scripts/import-mindbody.mjs --clients clients.csv --passes pricing.csv --dry-run
+
+# real import
+node scripts/import-mindbody.mjs --clients clients.csv --passes pricing.csv
+```
+
+Behavior:
+
+- **Idempotent by email** — re-running updates existing clients/passes, never
+  duplicates. Safe to re-export from Mindbody and re-import on cutover day.
+- Rows without a valid email are skipped and reported (Mindbody allows
+  email-less clients; Studio OS keys everything on email).
+- Passes for emails not in the clients file auto-create a bare client record.
+- A signed "Liability Waiver = Yes" column marks the waiver as signed so
+  clients aren't re-prompted.
+- Non-standard column names? Pass `--mapping mapping.json`:
+
+```json
+{
+  "clients": { "email": ["E-Mail-Adresse"], "firstName": ["Vorname"] },
+  "passes": { "remaining": ["Sessions Left"] }
+}
+```
+
+Keys you provide override the defaults; everything else keeps sane defaults
+(see `DEFAULT_MAPPING` in `src/services/importer.js`). Dates accept `M/D/YYYY`
+and ISO; money accepts `$1,500.00`-style strings.
+
+## Stripe setup (optional, bring-your-own account)
+
+Without Stripe, every purchase flow falls back to "pay at studio / FPS" and you
+activate purchases manually from the client profile — fully usable cash-only.
+
+1. Create a [Stripe](https://stripe.com) account (test mode is fine to start).
+2. Set env vars (`.env` or compose environment):
+   - `STRIPE_SECRET_KEY` — Developers → API keys
+   - `STRIPE_PUBLISHABLE_KEY`
+   - `STRIPE_WEBHOOK_SECRET` — see step 3
+3. Add a webhook endpoint in Stripe: `https://your-domain/webhooks/stripe`,
+   events `checkout.session.completed` and `customer.subscription.deleted`.
+   Copy the signing secret into `STRIPE_WEBHOOK_SECRET`.
+   (Local testing: `stripe listen --forward-to localhost:3000/webhooks/stripe`.)
+4. **Class packs** sell immediately via Checkout (price taken from the product;
+   optionally paste a Stripe Price ID on the product for Stripe-side pricing).
+5. **Memberships** are Stripe subscriptions: create a recurring Price in Stripe,
+   paste its `price_...` id into the plan in Admin → Products.
+
+Fulfillment is idempotent (keyed on the Checkout session id) — Stripe's webhook
+retries can't double-credit. Card data never touches your server; clients pay on
+Stripe-hosted Checkout. Set `BASE_URL` so success/cancel redirects and emailed
+links use your public domain.
+
+## Email (optional)
+
+Set `SMTP_HOST` (+ `SMTP_PORT`/`SMTP_USER`/`SMTP_PASS`/`SMTP_FROM`) to send
+booking confirmations, cancellation notices, waitlist promotions and magic
+links. Without SMTP, every email is written to `data/outbox/` as a `.eml` file
+and magic links are shown directly in the UI — everything remains testable.
+
+## Security
+
+What's protected out of the box:
+
+- **CSRF**: every state-changing form carries a session-bound token; POSTs
+  without a valid token get a 403. The Stripe webhook is exempt — it is
+  authenticated by Stripe's signature over the raw body instead.
+- **Rate limiting** (in-memory fixed window, per IP + route): magic-link
+  requests 5/15 min, admin login 10/15 min, public booking/buy POSTs
+  30/15 min. Over the limit → friendly 429. Behind a reverse proxy, set
+  `TRUST_PROXY=1` so limits key on the first `X-Forwarded-For` hop; without
+  it that header is ignored (it's spoofable).
+- Passwords are bcrypt-hashed; client self-service uses expiring HMAC-signed
+  magic links (no client passwords); sessions are signed `SameSite=Lax`
+  `HttpOnly` cookies; webhook fulfillment is idempotent.
+
+What's *not* there yet — plan accordingly:
+
+- **No 2FA** on staff logins.
+- The rate limiter is **single-instance and in-memory**: counters are
+  per-process and reset on restart. Fine for the one-container target; a
+  multi-instance deployment needs a shared store (or limit at the proxy).
+- **HTTPS is your reverse proxy's job** — run behind Caddy/Traefik/nginx.
+
+## Backups
+
+Admin → Settings → **Download backup** produces a consistent snapshot via
+SQLite `VACUUM INTO`. Or just copy `data/studio.db` while the app is stopped.
+It's one file — cron it anywhere.
+
+## Screenshots
+
+**Public booking site** — what your clients see. No account needed; the waiver is
+collected on first booking, and returning clients are matched by email so membership
+or pack credits apply automatically.
+
+| Schedule | Booking a class |
+|---|---|
+| ![Public schedule](docs/screenshots/public-schedule.png) | ![Booking form](docs/screenshots/public-booking.png) |
+
+**Buy page** — class packs and memberships, on *your* Stripe account (or pay-at-studio
+if you haven't connected Stripe).
+
+![Buy page](docs/screenshots/public-buy.png)
+
+**Admin** — dashboard, schedule, class roster with one-tap check-in, client profiles,
+and revenue reports.
+
+| Dashboard | Roster & check-in |
+|---|---|
+| ![Admin dashboard](docs/screenshots/admin-dashboard.png) | ![Roster](docs/screenshots/admin-roster.png) |
+
+| Schedule management | Client profile | Reports |
+|---|---|---|
+| ![Schedule](docs/screenshots/admin-schedule.png) | ![Client](docs/screenshots/admin-client.png) | ![Reports](docs/screenshots/admin-reports.png) |
+
+## Development
+
+```sh
+npm install
+npm test        # node:test + supertest, no network
+npm run dev     # --watch mode
+```
+
+Stack: Node 20+, Express, better-sqlite3 (WAL), EJS + HTMX + Pico.css
+(vendored). No frontend build. Tests cover the booking engine (capacity races,
+waitlist FIFO, credit deduct/refund, late-cancel policy), schedule
+materialization across timezones, the web flows, importer idempotency, and
+Stripe webhook fulfillment against a mock client.
+
+## Honest v0.1 limitations
+
+- **Single studio, single location, one timezone.**
+- See [Security](#security) for what is and isn't covered (no 2FA;
+  single-instance in-memory rate limiter; HTTPS via your reverse proxy).
+- Membership renewal bookkeeping is driven by Stripe webhooks; cash memberships
+  need manual renewal (mark paid each cycle).
+- Monthly-credit memberships reset on a simple cycle from `cycle_started_on`;
+  no proration.
+- Emails are plain text; no branded HTML templates yet.
+- English UI only (currency is a setting — no hardcoded symbols).
+- Reports are month-granularity tables + CSV; no charts.
+
+## Roadmap
+
+- Multi-location support
+- Branded/installable PWA per studio (custom colors, icon, name)
+- SMS reminders (Twilio-compatible, bring-your-own account)
+- Recurring cash membership invoicing + renewal reminders
+- Retail/POS, gift cards, video — explicitly out of scope for now, as are staff
+  payroll, per-instructor payouts, marketing automation, native apps, GDPR
+  export tooling and i18n.
+
+## License
+
+MIT

package/SPEC.md

@@ -0,0 +1,130 @@
+# Studio OS — self-hosted studio management ("the Mindbody escape hatch")
+
+Open-source, self-hosted booking/membership/class-pack management for boutique studios
+(yoga, pilates, martial arts, climbing, dance, small gyms). The structural wedge no SaaS
+rival can copy: **payments run on the operator's OWN Stripe account** — we never touch the
+money, charge no processing markup, no per-booking fees, no contracts.
+
+Target user: a studio owner currently paying Mindbody $139–599/mo + ~3.5% forced processing.
+Deployment target: one Docker container (or `npm start`) on a $5 VPS or a spare machine.
+
+## v0.1 scope (MUST all work)
+
+### Stack
+- Node 20+, Express, better-sqlite3 (WAL mode), server-rendered EJS templates + HTMX
+  (vendored locally, NO CDN at runtime), vendored Pico.css + one small custom stylesheet.
+  No frontend build step. No paid APIs. Everything works offline except Stripe/SMTP.
+- `node:test` + supertest for tests. Dockerfile + docker-compose.yml. `.env` config
+  (dotenv), `data/studio.db` SQLite file.
+- License MIT. Repo layout: `src/` (server), `src/routes/`, `src/db/` (schema+migrations+queries),
+  `src/services/`, `views/`, `public/` (css/js/manifest), `test/`, `scripts/` (seed, import),
+  `README.md`, `CHANGELOG.md`.
+
+### Domain model (SQLite tables)
+- `settings` (key/value): studio name, timezone (default Asia/Hong_Kong), currency (default HKD),
+  cancellation window hours (default 12), waiver markdown text, booking policy flags.
+- `users`: operator/staff logins (email, argon2/bcrypt hash, role: owner|staff). Session auth
+  (cookie, SQLite session store or signed cookie). First-run setup wizard creates the owner.
+- `instructors`: name, bio, active.
+- `class_types`: name, description, duration min, default capacity, drop-in price cents,
+  credits required (default 1), color.
+- `schedule_rules`: weekly recurring template (class_type, instructor, weekday, start time,
+  capacity override, active from/until) → materialized into `class_instances` on a rolling
+  8-week horizon (idempotent generator run at boot + daily + on rule change).
+- `class_instances`: datetime, class_type, instructor, capacity, status (scheduled|cancelled),
+  notes. One-off instances can be created directly.
+- `clients`: name, email (unique), phone, notes, waiver_signed_at, source (manual|import|self).
+- `passes` (class packs): client, name, credits_total, credits_remaining, expires_on,
+  price_paid_cents, source (purchase|import|manual).
+- `memberships`: client, plan name, status (active|paused|cancelled), started_on, renews_on,
+  stripe_subscription_id nullable, unlimited flag or credits/month.
+- `membership_plans`: name, price cents, interval (month), unlimited or N credits/month,
+  stripe_price_id nullable.
+- `bookings`: class_instance, client, status (booked|waitlist|cancelled|attended|no_show),
+  paid_with (pack|membership|drop_in_online|drop_in_manual|comp), pass_id nullable,
+  created_at, cancelled_at. Unique (class_instance, client) among non-cancelled.
+- `payments`: client, amount cents, currency, method (stripe|cash|fps|other), reference,
+  what (drop_in|pack|membership), stripe_session_id nullable, created_at.
+- `audit_log`: who, action, entity, at — append-only, for operator trust.
+
+### Booking rules (core logic — must be tested)
+- Book with: active membership (unlimited or monthly credits) → else pack with credits
+  (soonest-expiring first) → else drop-in (Stripe checkout if configured, else "pay at studio"
+  which records a pending manual payment).
+- Capacity enforced atomically (SQLite transaction). Full class → waitlist (FIFO). A
+  cancellation auto-promotes the first waitlisted booking and (if SMTP on) emails them.
+- Cancel ≥ cancellation-window hours before start → credit refunded to pack / no charge.
+  Late cancel → configurable: forfeit credit (default) or refund. No-show marking by staff.
+- Credits are deducted at booking time, refunded on eligible cancellation, in the same
+  transaction as the booking row.
+
+### Public site (no login needed)
+- `/` public schedule: next 14 days, filter by class type/instructor, studio branding from settings.
+- Class page → "Book" → enter name+email (or returning-client email). First booking shows the
+  waiver (markdown rendered) with required checkbox; `waiver_signed_at` stored.
+- Client self-service via signed magic links (HMAC token in email / shown on screen when SMTP
+  is off): view own upcoming bookings, cancel within policy. NO client passwords in v0.1.
+- Buy page: class packs and membership plans. With Stripe configured → Stripe Checkout
+  (packs = one-time, memberships = subscription); webhook `/webhooks/stripe` (signature-verified)
+  fulfills: creates pass / activates membership + payment row. Without Stripe → instructions page
+  ("pay at studio / FPS") and operator activates manually.
+- PWA: manifest.json + minimal service worker (cache static assets), mobile-first layout.
+
+### Admin (login required)
+- Dashboard: today's classes with live roster counts, week revenue total, expiring passes list.
+- Schedule management: CRUD class types, instructors, weekly rules, one-off classes,
+  cancel a class (auto-notifies + refunds credits of all bookings).
+- Roster per class: check-in (attended), no-show, add walk-in client, see paid_with per booking.
+- Clients: search, profile (bookings, passes, memberships, payments), add pass/membership
+  manually, record manual payment, edit waiver status, notes.
+- Reports: revenue by month (table), attendance by class type, CSV export of any report.
+- Settings: studio profile, currency, cancellation window, waiver text (markdown editor),
+  Stripe keys status (from env, read-only display), SMTP status, backup button (downloads
+  a copy of studio.db via SQLite `VACUUM INTO`).
+
+### Mindbody CSV importer
+`scripts/import-mindbody.mjs` + admin UI page. Accepts the standard Mindbody exports:
+- Clients export (First Name, Last Name, Email, Phone, ...) → clients.
+- "Pricing options"/pass export (Client, Pricing Option, Remaining, Expiration, ...) → passes.
+Column mapping via a JSON mapping file with sane defaults; unknown columns ignored; dry-run
+mode prints what would be created; idempotent by email (re-running updates, never duplicates).
+Ship a `test/fixtures/mindbody-*.csv` set of realistic fixtures (invented data, realistic shape).
+
+### Email (optional)
+SMTP via nodemailer, env-configured. When unset: emails are written to `data/outbox/` as .eml
+files and magic links are surfaced in the UI (so everything is testable without SMTP).
+Templates: booking confirmation, cancellation, waitlist promotion, magic link.
+
+### Stripe (optional, BYO account)
+Env: STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, STRIPE_PUBLISHABLE_KEY. When unset, all
+purchase flows fall back to manual/"pay at studio" and the admin sees a "Stripe not connected"
+hint. When set (test mode is fine): packs via Checkout one-time, memberships via Checkout
+subscription using `membership_plans.stripe_price_id` (admin field to paste a Price ID),
+webhook fulfillment, and payment rows with the Stripe session id. NEVER store card data.
+Write the integration against the official `stripe` npm package; all Stripe calls isolated in
+`src/services/stripe.js` and fully mockable — tests must not hit the network.
+
+### Non-negotiables
+- First-run experience: `npm install && npm start` → setup wizard (studio name, owner account,
+  timezone/currency) → seeded example class types optional. `npm run seed` creates a demo studio.
+- Every core booking rule covered by tests (capacity race, waitlist promotion, credit
+  deduct/refund, late-cancel forfeit, importer idempotency, webhook fulfillment with mocked
+  Stripe, magic-link auth). `npm test` green.
+- No network calls at boot or in tests. No telemetry. No mocks/placeholders in shipped code paths.
+- All timestamps stored UTC, rendered in the studio timezone.
+- README: 5-minute quickstart (Docker + bare Node), Mindbody migration guide (step-by-step:
+  which exports to download, how to run the importer), Stripe setup guide, screenshots section
+  placeholder, honest v0.1 limitations list, roadmap (multi-location, branded PWA, SMS).
+
+### Out of scope for v0.1 (list in README roadmap; do NOT build now)
+Multi-location, staff payroll, retail/POS, gift cards, video/livestream, marketing automation,
+native apps, per-instructor payouts, GDPR export tooling, i18n (English UI only, but no
+hardcoded currency symbols — use the currency setting).
+
+## Definition of done for v0.1
+`npm test` green; `npm start` boots on a clean machine; a full manual walkthrough works:
+setup wizard → create class type + weekly rule → instances appear on public schedule →
+guest books with waiver → operator sells a 10-pack manually → client books with credit →
+cancel refunds credit → roster check-in → revenue report shows the payments → Mindbody
+fixture import creates clients+passes → magic link lets the client cancel a booking.
+Docker build succeeds. README complete.

package/docker-compose.yml

@@ -0,0 +1,26 @@
+services:
+  studio:
+    build: .
+    ports:
+      - "3000:3000"
+    volumes:
+      - studio-data:/app/data
+    # Everything is optional — see .env.example. Uncomment the block and the
+    # variables you use. (An `environment:` key with only comments under it is
+    # invalid YAML for compose — keep the key commented until you need it.)
+    #environment:
+    #  BASE_URL: https://booking.example.com
+    #  APP_SECRET: change-me
+    #  TRUST_PROXY: "1"
+    #  SMTP_HOST: smtp.example.com
+    #  SMTP_PORT: "587"
+    #  SMTP_USER: user
+    #  SMTP_PASS: pass
+    #  SMTP_FROM: My Studio <noreply@example.com>
+    #  STRIPE_SECRET_KEY: sk_live_...
+    #  STRIPE_WEBHOOK_SECRET: whsec_...
+    #  STRIPE_PUBLISHABLE_KEY: pk_live_...
+    restart: unless-stopped
+
+volumes:
+  studio-data: