diff --git a/.github/workflows/prepare-release.yml b/.github/workflows/prepare-release.yml new file mode 100644 index 0000000..9c25512 --- /dev/null +++ b/.github/workflows/prepare-release.yml @@ -0,0 +1,62 @@ +# Start a release from GitHub (Actions → Prepare release → Run workflow): raises the version on a copy of dev, writes +# its CHANGELOG.md section (yarn release), and opens the pull request "Release v" into dev. Review and edit the +# changelog there, merge it, then open dev → main as usual. +# RELEASE_TOKEN (a fine-grained token: this repo, Contents and Pull requests read and write) opens the pull request as +# you, so `check` and the preview run on it; GitHub doesn't start workflows for pull requests its own token opens. +name: Prepare release + +on: + workflow_dispatch: + inputs: + kind: + description: 'patch (fixes), minor (new tools or features) or major (breaks how people use Ream)' + type: choice + options: [patch, minor, major] + default: minor + +permissions: + contents: write + pull-requests: write + +concurrency: prepare-release + +jobs: + prepare: + runs-on: ubuntu-latest + timeout-minutes: 5 + steps: + - uses: actions/checkout@v7 + with: + ref: dev + fetch-depth: 0 # the tags and history the changelog is made from + token: ${{ secrets.RELEASE_TOKEN || github.token }} + - uses: actions/setup-node@v7 + with: + node-version: 22 # scripts/release.ts is TypeScript, run directly; it needs only git + - name: Raise the version and write the changelog + id: release + run: | + node scripts/release.ts prepare "${{ inputs.kind }}" + echo "version=$(node scripts/release.ts version)" >> "$GITHUB_OUTPUT" + - name: Open the pull request into dev + env: + GH_TOKEN: ${{ secrets.RELEASE_TOKEN || github.token }} + VERSION: ${{ steps.release.outputs.version }} + run: | + branch="release/v$VERSION" + if git ls-remote --exit-code --heads origin "$branch" >/dev/null; then + echo "::error::$branch already exists: merge or delete its pull request first." + exit 1 + fi + git config user.name 'github-actions[bot]' + git config user.email '41898282+github-actions[bot]@users.noreply.github.com' + git switch -c "$branch" + git add package.json CHANGELOG.md + git commit -m "Release v$VERSION" + git push origin "$branch" + { + echo "Raises the version to $VERSION and adds its changelog section. Edit \`CHANGELOG.md\` here if the wording needs it; after merging, open the pull request from \`dev\` into \`main\` to release." + echo + node scripts/release.ts notes + } > body.md + gh pr create --base dev --head "$branch" --title "Release v$VERSION" --body-file body.md diff --git a/.github/workflows/web.yml b/.github/workflows/web.yml index 04d2808..ed7c8bf 100644 --- a/.github/workflows/web.yml +++ b/.github/workflows/web.yml @@ -127,10 +127,12 @@ jobs: apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }} accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }} command: pages deploy dist --project-name ream --branch main --commit-hash "${{ github.sha }}" --commit-message "v${{ steps.version.outputs.version }}" - - name: Tag the release and write its notes (the pull requests merged since the last one) + - name: Tag the release, with its CHANGELOG.md section as the notes env: GH_TOKEN: ${{ github.token }} - run: gh release create "v${{ steps.version.outputs.version }}" --repo "${{ github.repository }}" --target "${{ github.sha }}" --title "v${{ steps.version.outputs.version }}" --generate-notes + run: | + node repo/scripts/release.ts notes > notes.md + gh release create "v${{ steps.version.outputs.version }}" --repo "${{ github.repository }}" --target "${{ github.sha }}" --title "v${{ steps.version.outputs.version }}" --notes-file notes.md # the image for self-hosting: Intel/AMD and ARM, tagged with the version and latest. The site is built once, on # the runner's own platform; each platform's image only copies the files, so no emulation is needed. - uses: docker/setup-buildx-action@v4 diff --git a/AGENTS.md b/AGENTS.md index 7205801..e472ce4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -125,7 +125,7 @@ To add a tool: manifest, run, panel, three registry entries, and tests. Reuse th ## Platform seams -- Image codec: `codec()` / `setCodec()` in `image-core`. The app's worker sets `appCodec` (`image-core/browser`): our own decoders and encoders for PNG, JPEG, GIF and BMP, and the browser (OffscreenCanvas) only for WebP and for files ours refuse with `UnsupportedImage`. Tests call `setCodec(ownCodec)`; WebP can't be tested in Node. Decoders and encoders are pure and synchronous (`decodeJpeg`, `encodeJpeg`, `decodeGif`, `encodeGif`, `decodeBmp`, `encodeBmp`, `decodePng`, `encodePng`) and are used directly by tools that need more than one picture out (GIF frames, JPEG metadata segments). +- Image codec: `codec()` / `setCodec()` in `image-core`. The app's worker sets `appCodec` (`image-core/browser`): the browser's native codec (OffscreenCanvas) where ours is many times slower (JPEG read and written, opaque PNG written, WebP), ours for PNG reading, see-through PNG writing (a canvas premultiplies alpha, so lossless would stop being lossless), GIF and BMP, and ours again whenever the browser fails. Native JPEG reading keeps samples as stored (`colorSpaceConversion: 'none'`) like ours; the browser's JPEG adds an sRGB profile, so Compress image keeps only its JFIF header and puts the file's own segments back. Tests call `setCodec(ownCodec)`; the native paths can't be tested in Node and are checked in Chrome. Decoders and encoders are pure and synchronous (`decodeJpeg`, `encodeJpeg`, `decodeGif`, `encodeGif`, `decodeBmp`, `encodeBmp`, `decodePng`, `encodePng`) and are used directly where the codec can't do the job (GIF frames, palette PNGs (PDF to image keeps ours for its pages: small files for text), grey JPEGs). Compress PDF reads colour JPEGs through `Platform.decodeJpeg` (the browser's, as the renderer draws them) and the rest with ours. - Text on pictures: the engine has no font code. Panels draw text to a PNG with the browser canvas (`bitmaps.ts`: `textMark`, `pictureMark`, `trimmedPng`; `meme/caption.ts`) and put it in the options; `run.ts` only decodes and places it with `overlay`. Keep it that way; a Node test passes a ready-made PNG. `blur-image` is the one panel that imports engine functions (`apply.ts`): it shows the same operations on a 1400 px copy so the preview matches the saved file. - Flate: `deflate` / `inflate` in `core` use `CompressionStream` (async); `inflate` keeps its output when bytes follow the end of the data (a stream Length that counts a line break), which the platform stream rejects. - Renderer `Platform`: `imageFromRGBA` and `decodeJpeg`. Tests pass fakes. @@ -137,7 +137,7 @@ To add a tool: manifest, run, panel, three registry entries, and tests. Reuse th - `ToolPage.tsx`: files | preview | options at `xl`; at `lg` the options stay on the right with the files above the preview; stacked below that, options before the preview. Options are always the right-hand region. Tools with their own surface (crop, sign) set `placesActions` and render the `actions` prop (run button, progress, errors) beside their controls. A finished run opens a modal `` (download, keep editing, start over, use in another tool), not a card under the options. Locked PDFs open a password dialog and are replaced by a decrypted in-memory copy; the password is never stored. - `previewController.ts` (pure, fake-timer tested) runs the same engine as the Run button: **600 ms debounce**, cancels stale runs, keeps the last result on screen. `ready` states have `stale` (outdated; Run never reuses a stale result) and `computing` (dim and "Updating..."). Do not make the UI react per keystroke. - `previewWorker.ts` / `previewClient.ts`: one worker for inspect, render, unlock and metadata. The main thread never parses a PDF. Page canvases keep the old picture until the new one is ready (no flashing). -- Tool runs go through `runtime.ts` and `worker.ts` (progress, cancel, ZIP for several outputs). Limits: 50 files, 200 MB per file, 500 MB total. +- Tool runs go through `runtime.ts` and `worker.ts` (progress, cancel, ZIP for several outputs). Limits: 50 files, 200 MB per file, 500 MB total. One tool worker is kept warm between runs (`warmTool` loads the engine when a tool page opens; a run that starts while it's busy gets its own worker; cancelling terminates it). Each input carries a `key` (the same `File`, the same key), and `decodeFile` keeps decoded pictures under it (up to 512 MB, only for the current inputs), so a preview after an option change doesn't decode again. Run functions get a copy: they may change their pixels. - Office files preview as PDFs: `previewClient` sends the kind with the bytes (`officeKind` in `usePdfInfo.ts`, kept free of engine code), `previewWorker` converts once with `officeToPdf` from `@ream/tools/office-preview` and then inspects and draws it like a PDF, adding an "approximate" warning. `isPreviewable` (PDF or Office) decides what `Preview` and `Thumb` show. - Zoom: `ZoomBar`, `useZoom`, `zoomedWidth`, `renderWidthFor` and `useWidth` live in `@ream/ui` (`Zoom.tsx`). The Original/Result pane starts at fit width, with its `ZoomBar` (Fit width and Fit page) on the tabs row: `Preview` owns the zoom and `PdfView` reads it from `ZoomContext` and reports the size shown (no bar for pictures or text); panels that work on one page (Crop PDF, Sign PDF, Redact PDF, Fill PDF form) use `usePageZoom` (`tools/src/PageZoom.tsx`), which starts with the whole page in view and also offers Fit width. A zoom is a share of the actual size (a point is 4/3 CSS pixels), the page box is sized in CSS pixels inside a scrolling area, and everything drawn over it is positioned in fractions, so overlays scale with it. Pages are re-rendered at the shown size (in 200 px steps, at most 4000). - Edit PDF (`tools/src/edit-pdf`): @@ -156,7 +156,7 @@ To add a tool: manifest, run, panel, three registry entries, and tests. Reuse th - Routes (`App.tsx`, hash based): `#/tool/` the tool page, `#/tools`, `#/tools/pdf` and `#/tools/image` the tools home for a category (`Home.tsx`, `filterHref` in `TopBar.tsx`), `#/licence` and `#/notices` (`Legal.tsx`: the repo's `LICENSE` and `THIRD-PARTY-NOTICES.md`, imported `?raw` when the page opens) and `#/` (`Landing.tsx`); any other hash shows the landing page. The web-only pages share `Marketing.tsx` (nav, footer, `primary`/`secondary` link styles); app pages render `TopBar` (logo on the left; search and theme on the right; 1600 px like the pages) and `Breadcrumb` under it (All tools, the category, the tool; every level a link). The breadcrumb replaces visible headings on the tools home and tool pages (the `h1` is `sr-only`); on All tools the PDF tools and Image tools section titles link to their category. `focus` in `TopBar.tsx` is the shared focus ring. - 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//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 (`yarn version patch|minor|major`; `node scripts/release.ts check` fails on a version already tagged or older); the merge deploys production, tags `v` and creates a GitHub Release with generated notes. 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` 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` 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" 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). - 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, `