poli0981andClaude Opus 5.5 1b1e922fe2 Docs for v2.0, plus widget and CSP fixes (#100)
* docs: README, CHANGELOG and the docs suite brought up to v2.0

- README.md (new): what the site is, stack, how the Worker fits together,
  getting started on Node 26, commands, deploying with Workers Builds, the
  admin, security and licensing.
- CHANGELOG.md (new): v2.0.0 in Keep a Changelog form, plus a summary of the
  untagged 1.x months.
- SECURITY.md: admin.poli0981.dev, the bot gate and the widgets worker are in
  scope; tagged releases; reports go to a private repository; what the admin
  stores.
- THIRD-PARTY-NOTICES.md: every infrastructure service, with what each one is
  used for. CONTENT-LICENSE.md: the content submodule and /media images.
- poli0981.dev-docs v2.0: decision log D16–D19; architecture (worker entry,
  stack, repo layout, dev setup, ADR 09–11); design system (Glacier Teal
  tokens, theme modes, a11y rules); security (headers, single-key CIDR
  denylist, body limits, secrets table, supply chain on a public repo,
  admin hardening and Access recommendations, structured logs); Cloudflare
  setup (correct Workers Builds commands and the deploy incident, ADMIN_EMAILS,
  Access settings, observability); CI/CD as it runs today; bug reports,
  widgets, error pages, routes, roadmap with status and next steps,
  maintenance (TypeScript 7 bumps, rollback, R2/KV backup).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(changelog): link the documentation PR

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(widgets): Steam icons via Steam's Cloudflare CDN; optional GitHub token

Found by watching the first cron run of the new worker in production: no
image had been mirrored and two sources were stale.

- media.steampowered.com answers requests from Workers with 403, so every
  Steam icon mirror failed. cdn.cloudflare.steamstatic.com serves the same
  files to Workers (probed from Cloudflare's network).
- The GitHub events API allows 60 unauthenticated requests an hour per IP and
  Workers share egress IPs, so the feed was 403 for hours at a time. The
  worker now sends GITHUB_TOKEN when that optional secret exists (a
  fine-grained token with no permissions is enough for public data).
- YouTube's feeds/videos.xml currently answers 404 for both the channel and
  the uploads-playlist URL, from Cloudflare and from elsewhere; the worker
  already keeps the last good feed, so nothing changes there.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(csp): callout styles were blocked; the CSP check now covers styles

Lighthouse flagged a CSP violation on the one MDX post. Astro hashes the
styles of the components a page renders, but not of a component that only
appears inside MDX content: Callout's inline <style> shipped without its hash
and the browser refused it, so callouts were unstyled in production.

- Callout's rules move to src/styles/prose.css (the stylesheet Prose loads on
  every long-form page); the component has no <style> block any more.
- scripts/check-csp-hashes.mjs now hashes every inline <style> block against
  the page's policy and fails on any style attribute (a policy without
  'unsafe-inline' never allows one), with self-tests for both matchers. The
  build reports 339 style blocks across 64 pages, all hashed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(og): Number.parseInt in the colour mixer (Sonar S7773)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-24 11:48:47 +07:00

poli0981.dev

CI Quality Gate License: GPL-3.0

The personal site of Kokone (SkullMute) — dev portfolio, blog, short fiction and a hub for the SkullMute channel, in Vietnamese and English. Live at poli0981.dev.

Trang cá nhân của Kokone (SkullMute): dự án, blog, truyện ngắn và kênh SkullMute — song ngữ Việt/Anh. Tài liệu thiết kế đầy đủ (tiếng Việt) nằm trong poli0981.dev-docs/.

Stack

Layer Choice
Framework Astro 7 (static-first) with Svelte 5 islands
Styling Tailwind CSS 4, design tokens in src/styles/global.css ("Glacier Teal" palette)
Hosting Cloudflare Workers + Static Assets; KV, R2, Images, Rate Limiting, Access, Turnstile
Content Markdown/MDX in poli0981/content (git submodule src/content)
Search Pagefind (built after astro build)
Tooling Node 26 · TypeScript 7 (tsc) next to TypeScript 6 (astro check, typescript-eslint) · node:test · ESLint · Prettier · knip
Quality SonarCloud quality gate · CodeQL · OSV-Scanner · Snyk · Dependabot (3-day cooldown)

How it fits together

visitor ─▶ Cloudflare edge ─▶ src/worker.ts (every request, pages included)
            www → apex · IP denylist (KV) · admin host split · /media (R2) · /ext-img (KV)
            Turnstile gate (48-hour pass) · static pages from ASSETS · the rest → Astro app
                                                                      ├─ /api/report, /api/gate, /api/widgets, /api/health
                                                                      └─ admin.poli0981.dev (Cloudflare Access + JWT check)
workers/widgets (cron, every 45 min) ─▶ YouTube / Steam / GitHub ─▶ KV (data + mirrored images)

Almost every page is prerendered. The Worker entry runs first for every route so the bot gate, the denylist and the security headers also cover static pages. Details: 02_ARCHITECTURE.md and 06_SECURITY.md.

Getting started

Requirements: Node 26 (.nvmrc) and npm 11. The content submodule is public, so a plain clone works.

git clone --recurse-submodules https://github.com/poli0981/poli0981-dev.git
cd poli0981-dev
npm ci --ignore-scripts && npm run check-install-scripts
npx lefthook install
npm run types && npm run types:widgets
npm run dev

npm run dev runs Astro on workerd with local bindings. The admin works locally with a stand-in identity (dev@localhost); saving content needs a GITHUB_CONTENT_TOKEN in .dev.vars.

Commands

Command What it does
npm run dev Dev server (workerd, local KV/R2)
npm run build astro build → OG images → Pagefind index → CSP hash check
npm run preview Serve the build
npm run check astro check (TypeScript 6 language service)
npm run typecheck tsc from TypeScript 7 for the site and the widgets worker
npm run lint · npm run format:check · npm run knip ESLint · Prettier · unused files/exports
npm test · npm run test:coverage node:test suites; coverage writes coverage/lcov.info (80% line floor)
npm run smoke Runs the built Worker with wrangler dev and probes pages, headers, the gate and the denylist
npm run new:post Scaffold a post or story from docs/templates/
npm run check-exif · npm run strip-exif Refuse / remove GPS and camera metadata in images
npm run gen-notices Regenerate THIRD-PARTY-NOTICES.md (CI checks it)

Deploying

Cloudflare Workers Builds builds every push: main runs npx wrangler deploy, any other branch only npx wrangler versions upload (a preview version that takes no traffic). After a merge, https://poli0981.dev/api/health reports the running version and commit. The widgets worker deploys by hand: npx wrangler deploy --config workers/widgets/wrangler.jsonc. Setup from scratch: 07_CLOUDFLARE_SETUP.md; pipeline: 08_CI_CD.md; changes per release: CHANGELOG.md.

Admin

admin.poli0981.dev is the owner's editor: write and edit posts (commits to the content repo), upload images (transformed once into AVIF/WebP and stored in R2), manage gallery albums, publish (opens a submodule-bump PR that CI must pass), review an audit log and manage the IP denylist. It sits behind Cloudflare Access, and the Worker independently verifies the Access JWT (≤ 24 hours old) and an email allowlist on every request.

Security

Please report vulnerabilities privately — see SECURITY.md. Bug reports from the site's "Report a bug" button land in a private repository, not in this one's issues.

License

S
Description
No description provided
Readme GPL-3.0
7.9 MiB
0 Stars 1 Watchers 0 Forks
Languages
TypeScript 51.9%
Astro 19.4%
Svelte 16.3%
JavaScript 9.9%
CSS 2.5%