docs: add README, MIT license, and update .gitignore for open source

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
2026-11-02 20:16:27 -05:00
parent a0b02396c0
commit 77cd7dbd2b
3 changed files with 105 additions and 0 deletions

2
.gitignore vendored
View File

@@ -3,3 +3,5 @@ dist/
.wrangler/
.dev.vars
.superpowers/
chat-summaries/
docs/superpowers/

21
LICENSE Normal file
View File

@@ -0,0 +1,21 @@
MIT License
Copyright (c) 2026 VCR Calendar 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.

82
README.md Normal file
View File

@@ -0,0 +1,82 @@
# VCR Calendar
A zero-JavaScript, server-rendered weekly calendar for [voidzero Community Radio](https://voidzero.io) (VCR) and [Small Group](https://smallgroup.live) podcast schedules. Built on Cloudflare Workers.
## Features
- **Week grid view** — CSS Grid calendar with half-hour time slots, colored show blocks, and live-now indicators
- **Agenda view** — day-by-day breakdown below the grid
- **Show detail pages** — description, hosts, website/feed links, and schedule badges
- **Timezone conversion** — Eastern, Central, Pacific, UTC, and Amsterdam with cookie-persisted preference
- **Light / Dark / System themes** — cookie-persisted, zero-JS theme switching via server-rendered links
- **Overnight show support** — shows crossing midnight render correctly across day boundaries and timezones
- **Fully server-rendered** — no client-side JavaScript; all interactivity through links and `Set-Cookie` headers
- **Week navigation** — browse past and future weeks via date picker
## Tech Stack
- **Runtime:** [Cloudflare Workers](https://workers.cloudflare.com)
- **Language:** TypeScript
- **Rendering:** Server-side HTML string templates
- **Styling:** Inline CSS (single `<style>` block, no external files)
- **Testing:** [Vitest](https://vitest.dev) with [`@cloudflare/vitest-pool-workers`](https://developers.cloudflare.com/workers/testing/vitest-integration/)
- **Deploy:** [Wrangler](https://developers.cloudflare.com/workers/wrangler/)
## Getting Started
```bash
npm install
npm run dev # local dev server on http://localhost:8787
npm test # run test suite
npm run deploy # deploy to Cloudflare Workers
```
Requires a [Cloudflare account](https://dash.cloudflare.com/sign-up) and [`wrangler` authentication](https://developers.cloudflare.com/workers/wrangler/commands/#login) for deployment.
## Project Structure
```
src/
├── index.ts # Worker entry point and router
├── schedule.json # Show roster (times in America/New_York)
├── preferences.ts # Cookie/query param preference resolution
├── types.ts # TypeScript type definitions
├── time/
│ ├── zones.ts # Timezone config and conversion (Intl.DateTimeFormat)
│ └── week.ts # Week boundary calculations
├── render/
│ ├── page.ts # HTML shell, controls bar, header/footer
│ ├── week-grid.ts # CSS Grid week view renderer
│ ├── week-page.ts # Week page composition (grid + agenda)
│ ├── agenda.ts # Day-by-day agenda renderer
│ ├── show-detail.ts # Individual show detail page
│ ├── not-found.ts # 404 page
│ └── utils.ts # Shared render helpers
└── style/
└── css.ts # Complete CSS as template literal
```
## Adding / Editing Shows
All show data lives in [`src/schedule.json`](src/schedule.json). Each show entry includes:
- Schedule (day, start/end time, timezone, recurrence)
- Metadata (name, slug, description, hosts, accent color)
- Links (website URL, RSS feed URL)
- Flags (`isVcr`, `isSmallGroup`, `isActive`)
Times are in 24-hour format. Overnight shows use a `+1` suffix on `endTime` (e.g., `"01:00+1"` means 1:00 AM the next day).
## URL Parameters
| Param | Values | Default |
|---------|---------------------------------------------------|------------|
| `tz` | `eastern`, `central`, `pacific`, `utc`, `amsterdam` | `eastern` |
| `theme` | `light`, `dark`, `system` | `system` |
| `mode` | `active`, `all` | `active` |
| `week` | `YYYY-MM-DD` (any date in the target week) | current |
| `reset` | `1` | — |
## License
[MIT](LICENSE)