forme-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 863572f23813b5d5090e945bbfcd36d225584aa728aaed8ff1c3e7ca73e4cdd6
+  data.tar.gz: b152a91177bffc61c05cdacabc76fb85262ed70947ba831da4109baf3d435724
+SHA512:
+  metadata.gz: 7e785dc05aa0846e664610eba4a013c9006731ea5b5e4295bd0b517527e70fdde7df931a6778c31b2097395630b152a98ffe8dfc85c129cb7a25dd9e3c8c7ea2
+  data.tar.gz: 8361e47d81f21658f310384205290cb6590ab1c0b663ce6543c324f16270dfdee1d1002d2bdb11ccd685757bd0b4fa7e845fb1dee2bffcf585607019016d90fc

data/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+### Added
+
+- Native HTML-to-PDF rendering with binary output and preserved warnings/pass counts.
+- CSS and local TTF options, typed load/render errors and explicit startup verification.
+- Independent native result ownership, cleanup and concurrent rendering.
+- Optional Rails template adapter with caller-owned permissions and responses.
+- Source and native packaging for macOS ARM64 and Linux AMD64 glibc.
+- Ruby CI across 3.2, 3.3, 3.4 and 4.0; clean source/native package installs
+  on Ruby 3.3 and distribution qualification jobs.
+- Public installation, rendering, Rails, development, security and release guides.
+
+### Hardened
+
+- Preserve result ownership during Ruby thread cancellation and metadata failures.
+- Replace rebuilt libraries atomically and retain runtime-user read permissions.
+- Reject empty package verification runs and missing third-party license text.
+
+### Native baseline
+
+- Forme HTML 0.24.0 at `f408920e632c59da0651b5b6d32f8c1397477673`.
+- Build toolchain: Rust 1.94.0; target minimums macOS 15 and glibc 2.28.
+- RubyGems publication and qualification of the final release commit are pending.
+
+### Release preparation
+
+- Prepare macOS ARM native packages and a glibc 2.28 Linux AMD64 build, with
+  qualification jobs for UBI 8/9/10, Ubuntu 24.04/26.04 and Arch Linux.
+- Add pinned GitHub Actions, dependency/security checks, contribution templates
+  and validated trusted publishing with release attestations.
+- Document narrowly scoped native dependency audit exceptions and repository setup.
+- Deduplicate and sort license files so notices match across macOS and Linux.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,18 @@
+# Community Code of Conduct
+
+Forme Ruby welcomes contributors of every background and experience level.
+Treat people with respect, give specific and constructive feedback, and make
+room for different perspectives. Discuss the code and ideas without attacking
+the person. Respect privacy and use synthetic data in public examples.
+
+Harassment, discriminatory language, threats, unwanted sexual attention,
+publishing private information, and sustained disruption are unacceptable.
+These expectations apply in repository discussions, issues, pull requests and
+other spaces where someone represents the project.
+
+Report concerns privately to ajaya@clearstack.io. Include relevant links and
+context without sharing more personal information than necessary. Maintainers
+will review reports discreetly, consider the affected people's needs, and may
+request changes, remove content, restrict participation or ban participants.
+Maintainers are expected to follow these standards too. Reporters may request
+reconsideration by replying with additional context.

data/CONTRIBUTING.md

@@ -0,0 +1,67 @@
+# Contributing to Forme Ruby
+
+This guide covers local builds, verification and the boundary of the public gem.
+Use synthetic documents and assets that can be redistributed.
+
+## Set up a checkout
+
+Use CRuby 3.2+ and Rust/Cargo 1.94.0, a native linker and make. From the repository:
+
+```bash
+bundle install
+bundle exec rake compile
+bundle exec rspec
+cargo test --locked --manifest-path ext/forme_pdf/Cargo.toml
+bundle exec standardrb
+bundle exec bundler-audit check --update
+cargo install cargo-audit --version 0.22.2 --locked
+cargo audit --file ext/forme_pdf/Cargo.lock
+```
+
+`compile` retains Cargo build output for subsequent development. Source-gem
+installation removes its temporary target directory. Build the extension before
+running Ruby examples; the loader never compiles during `require`.
+
+## Understand the code
+
+- `lib/forme_pdf.rb` is the public facade; `lib/forme_pdf/` contains loading,
+  rendering, immutable results, errors and the explicit Rails adapter.
+- `ext/forme_pdf/` owns the Rust C ABI and locked upstream dependencies.
+- `spec/` tests Ruby behavior and ownership; Rust tests cover the native boundary.
+- `script/` and `.github/workflows/` own notices, installed-package checks and releases.
+
+Keep consumer templates, logos, data access and infrastructure conventions out
+of the gem. Preserve per-render ownership, explicit lengths and cleanup in
+`ensure`. Do not introduce global result buffers or runtime downloads.
+
+## Test packaging
+
+```bash
+ruby script/notices.rb
+bundle exec rake 'package[source]'
+bundle exec rake 'package[native]'
+ruby script/test_packages.rb
+```
+
+The installed-package script installs every package in `pkg/` into temporary
+GEM_HOME directories, then renders outside the checkout. Keep only packages for
+the local platform and source in that directory. Pass package filenames as arguments to test only those artifacts.
+It fails if no packages exist.
+CI performs clean source/native installation on the supported platforms.
+
+Regenerate and review notices after dependency changes. Notice generation fails
+when a dependency has no license text; documented version-specific fallbacks live
+under `script/licenses/`. Retain fixture font licenses as well.
+
+## Submit a change
+
+Explain the user-visible behavior, rationale and checks run. Add meaningful
+regression coverage for behavior changes. Use StandardRB and update guides and
+CHANGELOG when the public API, installation or support matrix changes.
+See [release preparation](docs/releasing.md) before packaging a version.
+
+Validate workflow changes with `actionlint`. Linux package reproduction uses
+`script/ci/build-linux.sh` inside the pinned UBI 8 image in `ci.yml`; do not run
+that container setup script directly on your workstation. Review
+[security exceptions](docs/security-exceptions.md) whenever dependencies or the
+native API change.

data/LICENSE

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

data/NOTICE

@@ -0,0 +1,5 @@
+forme-ruby is an independent binding, not an official Forme project.
+Forme: https://github.com/danmolitor/forme
+Pinned revision: f408920e632c59da0651b5b6d32f8c1397477673
+Forme is MIT licensed. Native distributions must include upstream and dependency
+license notices generated during their build (see third-party notices).

data/README.md

@@ -0,0 +1,71 @@
+# forme-ruby
+
+[![CI](https://github.com/clearstackio/forme-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/clearstackio/forme-ruby/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Render HTML and print CSS to PDF inside Ruby, using the Rust
+[Forme](https://github.com/danmolitor/forme) engine. No browser, Node.js,
+WebAssembly or separate rendering service is needed.
+
+This is an independent MIT-licensed binding maintained by
+[ClearStack](https://github.com/clearstackio), not an official upstream project.
+**0.1.0 is in preparation; RubyGems publication is pending.**
+
+## Getting started
+
+Until the first RubyGems release, use the Git repository and commit the resolved
+lockfile. Git installation compiles the native extension and requires Rust/Cargo
+1.94.0, a linker and make:
+
+```ruby
+gem "forme-ruby", github: "clearstackio/forme-ruby", branch: "main", require: "forme_pdf"
+```
+
+```ruby
+require "forme_pdf"
+
+pdf = FormePDF.render_html("<h1>Hello from Ruby</h1>")
+File.binwrite("hello.pdf", pdf)
+```
+
+Ruby 3.2 or later is required. Planned native packages target Apple Silicon macOS
+15+ and Linux AMD64 glibc 2.28+ and need no compiler. Source installs require
+network access to locked upstream dependencies. See [installation](docs/installation.md).
+
+## Native platform targets
+
+| Native gem | Qualification environments |
+| --- | --- |
+| `arm64-darwin` | Apple Silicon macOS 15 and 26 |
+| `x86_64-linux-gnu` | Red Hat UBI 8, 9 and 10; Ubuntu 24.04 and 26.04; Arch Linux rolling |
+
+These are the release CI targets; qualification of this prepared commit is
+pending. Red Hat testing uses official UBI images, not RHEL certification.
+Linux ARM64, Windows and Alpine/musl binaries are not provided. See the
+[installation guide](docs/installation.md) for Ruby and source-build requirements.
+
+## Using Rails
+
+Authorize and select application data first, then render explicitly:
+
+```ruby
+html = render_to_string(template: "invoices/pdf", layout: "pdf", formats: [:html])
+send_data FormePDF.render_html(html),
+  type: "application/pdf", disposition: "inline", filename: "invoice.pdf"
+```
+
+Rails is optional. The [Rails guide](docs/rails.md) also covers the opt-in
+`FormePDF::Rails` adapter. The gem installs no middleware or routes.
+
+## Learn more
+
+- [Rendering guide](docs/rendering.md): CSS, fonts, diagnostics and error handling.
+- [Development](CONTRIBUTING.md): build, test and contribute.
+- [Community guidelines](CODE_OF_CONDUCT.md): participating respectfully.
+- [Release guide](docs/releasing.md): package qualification and future publication.
+- [Changelog](CHANGELOG.md), [license](LICENSE) and [third-party notices](THIRD_PARTY_LICENSES.txt).
+
+Use trusted HTML and assets. The engine can read local image paths and is not a
+sandbox for untrusted documents. See [security](SECURITY.md). Report reproducible
+bugs through [GitHub issues](https://github.com/clearstackio/forme-ruby/issues)
+with synthetic input, Ruby/platform versions and renderer diagnostics.

data/SECURITY.md

@@ -0,0 +1,17 @@
+# Security
+
+Render trusted HTML and caller-selected assets only. Forme can read local image
+paths and consumes CPU/memory in the host process. It is not an HTML sandbox;
+thread cancellation is not a reliable rendering timeout.
+
+Keep confidential documents out of logs and public issue attachments. Use a
+minimal synthetic reproduction when reporting a problem. Send potential
+security vulnerabilities privately to ajaya@clearstack.io rather than posting
+sensitive details publicly. No response-time guarantee is offered.
+
+The initial 0.1.0 release is still in preparation. Before deployment, qualify the
+exact package and pinned native dependencies on your application's target.
+
+Dependency audit exceptions and their call-path evidence are recorded in
+[the security review](docs/security-exceptions.md). They must be re-reviewed
+when the pinned engine or public native interface changes.