Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 8 additions & 3 deletions .github/workflows/web.yml
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
# Ream's pipeline. Linux only, a few minutes a run, inside GitHub's free allowance.
# pull request into dev check, then a preview deploy (<branch>.ream-bqb.pages.dev) with its link on the PR
# pull request into main check, and the version must be new (a release: see CONTRIBUTING.md)
# merge into main check, then production (ream.deityhub.com), the v<version> tag, a GitHub Release and the
# pull request into main check; a new version is a release (see CONTRIBUTING.md), the same version as the last
# release is not (a docs-only change) and ships nothing
# merge into main check, then, only when the version is new, production (ream.deityhub.com), the v<version> tag, a GitHub Release and the
# Docker image (ghcr.io/deityhub/ream, docker.io/deityhub/ream)
# A released version can be put back with the Deploy a version workflow (deploy-version.yml).
# Plain pushes to other branches run nothing. `check` is the status the branch rules require
Expand All @@ -26,6 +27,8 @@ jobs:
check:
runs-on: ubuntu-latest
timeout-minutes: 20
outputs:
release: ${{ steps.release.outputs.release }}
steps:
- uses: actions/checkout@v7
with:
Expand All @@ -37,6 +40,8 @@ jobs:
- name: The version is new (releases only)
if: github.base_ref == 'main' || github.ref == 'refs/heads/main'
run: node scripts/release.ts check
- id: release # false when v<version> is already tagged: production and the tag are skipped
run: echo "release=$(node scripts/release.ts pending)" >> "$GITHUB_OUTPUT"
- run: yarn install --immutable
- run: yarn typecheck
- run: yarn test
Expand Down Expand Up @@ -106,7 +111,7 @@ jobs:
gh pr comment ${{ github.event.pull_request.number }} --repo ${{ github.repository }} --body "$body" --edit-last --create-if-none

production:
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
if: github.event_name == 'push' && github.ref == 'refs/heads/main' && needs.check.outputs.release == 'true'
needs: check
runs-on: ubuntu-latest
timeout-minutes: 10
Expand Down
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -159,7 +159,7 @@ To add a tool: manifest, run, panel, three registry entries, its page text in `p
- SEO (`seo.ts`, `seoHead.ts`, `seoPlugin.ts`, `ToolAbout.tsx`, `packages/tools/src/seo/`): the build (`seoPlugin`, after the bundle) writes one HTML file per route from the built `index.html` (`tool/merge-pdf/index.html`...): its own `<title>`, description, canonical address, Open Graph and Twitter tags, JSON-LD (landing: `WebSite` + `WebApplication`; tools: `WebApplication` + `BreadcrumbList`; marked `data-seo`) and plain text inside `#root` (`main.seo`, styled in `index.css`) that the app replaces when it starts. It also writes `404.html` (needed: without it Cloudflare Pages treats the site as an SPA and answers every unknown address with 200) and `sitemap.xml` (indexable routes only: not the licence, notices or 404 pages). `pageSeo(route)` is the one source for all of it; `seoHead.applyHead` (lazy) keeps the head in step while moving around the app. A tool's words (`title` at most 60 characters ending in "| Ream", `description` 70 to 155, `intro`, three `points`, two or more `faq`) live in `packages/tools/src/seo/{pdf,convert,image}.ts` and also show under the tool (`ToolAbout`, lazy: four framed cells, shown only while no file is added). Write only what the tool really does and where it stops (no OCR, no certificate signatures, Office conversions are approximate). `SITE` (`https://ream.deityhub.com`) in `seo.ts` is every canonical address, also from a self-hosted copy. The social card is `apps/web/public/og.png`, made by `node scripts/og.ts`.
- Tools home (`Home.tsx`, at most 1600 px wide) is drop-first: the `Dropzone` `bar` layout, and dropped files handed to a tool through `handoff.ts`, the same mechanism as "Use in another tool".
- Docker: `Dockerfile` builds the site with Node (on the build machine's platform) and serves it with `nginxinc/nginx-unprivileged` (non-root, port 8080). Its NGINX site is generated from `apps/web/public/_headers` by `scripts/nginx-conf.ts`, so change headers there only. The image build skips the typecheck (tests are left out by `.dockerignore`; CI typechecks anyway). `check` builds and runs it and checks the page, the headers, `sw.js` not being cached, the manifest's type, a 404 and a non-root user; the release pushes amd64 and arm64 images to `ghcr.io/deityhub/ream` and, with `DOCKERHUB_USERNAME`/`DOCKERHUB_TOKEN` set, `docker.io/<user>/ream`, tagged with the version and `latest`. Containers can't start in this Mac's Docker; test a server inside a throwaway `docker build` (start it in a `RUN`, query it with curl) or rely on CI.
- Versions: the root `package.json` `version` (semver, starting at 0.1.0) is the release version. A pull request into `main` must raise it and have its `CHANGELOG.md` section: `yarn release patch|minor|major` (`scripts/release.ts prepare`) writes both, the section from the pull requests merged since the last tag (first-parent merges of `dev`, their titles and links; earlier releases skipped), and `node scripts/release.ts check` fails on a version already tagged or older or one without a section. The merge deploys production, tags `v<version>` and creates a GitHub Release whose notes are that section (`release.ts notes`). `.github/workflows/prepare-release.yml` (Actions → Prepare release) runs `prepare` on `dev` and opens the "Release v<version>" pull request into `dev`, as the `RELEASE_TOKEN` secret so `check` and the preview run on it. The version is in the footer (`__APP_VERSION__`, defined in `vite.config.ts`, declared in `version.d.ts`) and in the offline cache's name. `.github/workflows/deploy-version.yml` builds a released tag again and deploys it to production (rollback when the Cloudflare dashboard's can't).
- Versions: the root `package.json` `version` (semver, starting at 0.1.0) is the release version. A pull request into `main` that ships a change must raise it and have its `CHANGELOG.md` section (leaving the version as the last release's makes it a non-release, such as a docs-only change: `check` passes and the merge skips production, the tag and the image, through `release.ts pending`): `yarn release patch|minor|major` (`scripts/release.ts prepare`) writes both, the section from the pull requests merged since the last tag (first-parent merges of `dev`, their titles and links; earlier releases skipped), and `node scripts/release.ts check` fails on a version older than the latest tag or one without a section. The merge deploys production, tags `v<version>` and creates a GitHub Release whose notes are that section (`release.ts notes`). `.github/workflows/prepare-release.yml` (Actions → Prepare release) runs `prepare` on `dev` and opens the "Release v<version>" pull request into `dev`, as the `RELEASE_TOKEN` secret so `check` and the preview run on it. The version is in the footer (`__APP_VERSION__`, defined in `vite.config.ts`, declared in `version.d.ts`) and in the offline cache's name. `.github/workflows/deploy-version.yml` builds a released tag again and deploys it to production (rollback when the Cloudflare dashboard's can't).
- Crawlers: `apps/web/public/robots.txt` allows search engines and blocks AI training crawlers only (AI search and assistant fetchers and link-preview bots stay allowed, on purpose); `crawlers.test.ts` pins both lists, so adding a bot to one list means changing the test too. `_headers` ends with host rules (`https://:project.pages.dev/*`) that make the `pages.dev` addresses `noindex`; `scripts/nginx-conf.ts` skips rules for a whole address.
- Hosting: Cloudflare Pages, deployed by `.github/workflows/web.yml`: a pull request into `dev` runs `check` and gets a preview (its link is commented on the PR), a pull request into `main` runs `check`, a merge into `main` runs `check` and deploys production. Plain pushes run nothing. `check` is the status `.github/rulesets/protect-dev-main.json` requires (import it under Settings → Rules once the repo is public: rulesets aren't free on private repos). `apps/web/public/_headers` holds the security headers: the CSP allows only the site's own files, plus `api.fontsource.org` and `cdn.jsdelivr.net` in `connect-src` for Download free fonts, and no inline scripts or styles (`style-src 'self'`: React's `style` props are fine, `<style>` elements and `style="..."` strings are not). A new network host or inline style needs the policy changed, and the user asked first (the network rule above). Check with `wrangler pages dev` and a `securitypolicyviolation` listener.
- PWA: `manifest.webmanifest` and `icons/` in `apps/web/public` (PNGs from `apps/web/icons/icon.svg` by `node scripts/icons.ts`; square, full bleed, the mark inside the maskable safe zone). `apps/web/sw.js` is plain JS, outside `src`, registered as `/sw.js` with scope `/`: the `serviceWorker` plugin in `vite.config.ts` writes it into `dist` after the build with every file's name (minus `.woff` fallbacks, the non-Latin Office fonts, which it keeps when first used, and what only crawlers or the 404 need) and a version hashed from their contents. Each page is kept under its folder's address (`./`, `tool/merge-pdf/`) because Pages redirects `.../index.html` to the folder. A navigation that fails offline gets its own kept page, else `./` (the app routes by address). Cache lookups use `ignoreVary` (a host sending `Vary: Origin` made every module script miss its kept copy). Navigations are network first, everything else cache first. A new version waits until the user clicks Reload in `UpdateBar.tsx` (`pwa.ts` posts `switch`; the page reloads on `controllerchange` only after that, since the first worker's `clients.claim` changes the controller too). `pwa.ts` also keeps the `beforeinstallprompt` event for the landing page's Install Ream button. The worker is registered in production builds only: `yarn dev` has none. To test offline for real, serve the build with `wrangler pages dev`, let the worker fill its cache, then stop the server (CDP's offline emulation doesn't reach the worker's own requests).
Expand Down
2 changes: 1 addition & 1 deletion docs/deploy.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ The release version is the root `package.json` `version` (semantic versioning: `

1. Work reaches `dev` through pull requests; each gets a preview.
2. To release, run Actions → **Prepare release** → Run workflow and pick `patch`, `minor` or `major`. It does the step below on a copy of `dev` and opens the pull request "Release v<version>" into `dev`; edit the changelog there if needed and merge it. It needs the `RELEASE_TOKEN` secret to get `check` and a preview on that pull request (see below); without it the pull request opens with no checks. Or do it by hand: branch from `dev` (`release/v<version>`) and run `yarn release patch` (fixes), `minor` (new tools or features) or `major` (anything that breaks how people use Ream). It raises the version (counted from the latest tag: `git fetch --tags` first) and adds a section to `CHANGELOG.md` listing the pull requests merged since the last release, each with its link. Edit the section into plain words if you like, commit `Release v<version>`, and merge it into `dev` through a pull request.
3. Open the pull request from `dev` into `main`. `check` fails while the version is one already released or older, or `CHANGELOG.md` has no section for it (`node scripts/release.ts check`).
3. Open the pull request from `dev` into `main`. A version that is already released means this is not a release (a docs-only change): `check` passes and the merge deploys nothing, tags nothing and builds no image. Otherwise `check` fails while the version is older than the latest release, or `CHANGELOG.md` has no section for it (`node scripts/release.ts check`).
4. Merging it deploys production with the version in Cloudflare's deployment message, tags `v<version>`, creates a GitHub Release whose notes are the version's `CHANGELOG.md` section, and publishes the Docker image.

`RELEASE_TOKEN` is a fine-grained personal access token (GitHub → Settings → Developer settings → Fine-grained tokens): repository access only `Deityhub/ream`, permissions **Contents** and **Pull requests** read and write. Save it as a repository secret (Settings → Secrets and variables → Actions). It expires on the date you choose; make a new one when it does. GitHub doesn't run workflows for pull requests its own token opens, which is why the workflow uses yours. Like any manual workflow, **Prepare release** shows in the Actions tab only once it is on `main`.
Expand Down
9 changes: 8 additions & 1 deletion scripts/release.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
// The release version (the root package.json's "version", tagged v<version> when it reaches main) and its CHANGELOG.md section.
// node scripts/release.ts prepare patch|minor|major raise the version and write its changelog section (yarn release ...)
// node scripts/release.ts check fail unless the version is new, higher than every released one, and in the changelog (PRs into main)
// node scripts/release.ts check PRs into main: pass when the version is already released (nothing ships, e.g. a docs-only change); otherwise it must be higher than every released one and in the changelog
// node scripts/release.ts pending print true when v<version> isn't tagged yet (a merge into main releases), else false
// node scripts/release.ts version print it (the release job's tag and deploy message)
// node scripts/release.ts notes print its changelog section (the GitHub Release's text)
import { execFileSync } from 'node:child_process'
Expand Down Expand Up @@ -30,6 +31,7 @@ const latest = () =>
.filter((v): v is number[] => !!v)
.sort(newer)
.at(-1)
const released = () => git('tag', '--list', `v${version}`).trim() !== ''
const changelog = () => (existsSync(logPath) ? readFileSync(logPath, 'utf8') : '')
/** the text under "## <v>" up to the next section, or null when there is none */
const section = (v: string) => {
Expand Down Expand Up @@ -57,7 +59,12 @@ function entries(from: string | null): string[] {
const mode = process.argv[2]
if (mode === 'version') console.log(version)
else if (mode === 'notes') console.log(section(version) ?? fail(`CHANGELOG.md has no section for ${version}.`))
else if (mode === 'pending') console.log(!released())
else if (mode === 'check') {
if (released()) {
console.log(`Version ${version} is already released: this change is not a release, so nothing will be deployed.`)
process.exit(0)
}
const last = latest()
if (last && newer(own, last) <= 0) fail(`Version ${version} is already released or older than the latest release (${last.join('.')}). Raise it in this pull request: yarn release patch, minor or major.`)
if (!section(version)) fail(`CHANGELOG.md has no section for ${version}, or it is empty. yarn release patch, minor or major writes one.`)
Expand Down
Loading