postnhost 0.0.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58a5e825dc2b90b41ca5409f379a5ef6257b6d05de4cec3e7dc517d52cd045fd
-  data.tar.gz: ffae44f7bc9a560d21a8d910b16ff7e4bc7aac14819ebe01b9e28f101b2012da
+  metadata.gz: 1558c66e1ac90ab08507a78ffea0bac3294003f1ac89107090a2e0dd27e234d8
+  data.tar.gz: 95d7eaa5879b8b964c21a50b73ee87a941b577341b6a0a55f824fb7bdbedc1eb
 SHA512:
-  metadata.gz: 6ea72f1636e28368c812810ce70784a4a0067477596b01d7655532d667df81b2016186a6bea73fc639cd3a07bbaa376f0a2f4ba211bba02cbd09f12fa60594c0
-  data.tar.gz: 5f8cf9da3f29af73e5ab9e8d612762ee16220f9acda35eac2bf8386ff5a08b68374812d682a5fb68e2af220840fa60a0ef12993c78f03f448d5d4d4115c76702
+  metadata.gz: 54a365175843db9416fa0be1725e0acd6cc86574b81f8b8e6dccec2c4dc029161998bbd9901d1ed0c62768f30a46234b622b533395211f63d23592cd4910267c
+  data.tar.gz: 759fec551c44bd9060c87d183468aed04875881733e163262bf01100562837f2b6c1999379a80204ce1e5b603d26a0f1e36f74510173349d9a0596ffed0e8cfb

data/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to PostnHost are documented in this file.
+
+## [0.1.1] - 2026-08-31
+
+### Fixed
+
+- Scoped packaged and host-generated CSS to PostnHost layouts and replaced competing stylesheets with one combined host build that transparently shadows the packaged logical asset.
+- Corrected installer, template customization, Tailwind setup, and production checklist instructions.
+
+## [0.1.0] - 2026-08-29
+
+First open source release of PostnHost.
+
+### Added
+
+- Mountable Rails CMS engine with a built-in dashboard, onboarding, session-based authentication, and user management.
+- Draft and snapshot-based publishing for articles, pages, and translated variants, including scheduled publishing, unpublishing, bulk transitions, and version restoration.
+- Multilingual content, localized routes, language switching, locale-aware metadata, and optional OpenAI-assisted translations.
+- Rich text editing, image uploads and processing, categories, multiple authors, article suggestions, navigation management, static pages, and site-wide settings.
+- Public search, sitemaps, canonical URLs, hreflang tags, structured metadata, and HTTP and fragment caching with publication-aware invalidation.
+- Three packaged public templates: Default, Swiss Editorial, and Workspace Journal.
+- Generators for installation, CMS users, public view overrides, locales, static pages, and host Tailwind integration.
+- Precompiled JavaScript and CSS assets with Propshaft and Sprockets support, requiring no frontend toolchain in host applications.
+- Support for Ruby 3.4 and 4.0 with Rails 7.2, 8.0, and 8.1.
+
+### Credits
+
+Authored by Kirill Shevchenko (Ruby/Rails engineering) and Maxim Sova (technical SEO expertise).
+
+[0.1.1]: https://github.com/postnhost/postnhost/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/postnhost/postnhost/releases/tag/v0.1.0

data/{LICENSE.txt → LICENSE}

@@ -1,6 +1,6 @@
-The MIT License (MIT)
+MIT License
 
-Copyright (c) 2025 Kirill Shevchenko
+Copyright (c) 2025-2026 Kirill Shevchenko and Maxim Sova
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -9,13 +9,13 @@ 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 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.
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -1,39 +1,367 @@
-# Postnhost
+<h1 align="center" style="border-bottom: none">
+  <div>
+    <a href="https://postnhost.com">
+      <img alt="PostnHost" src="app/assets/images/postnhost/logo.webp" width="200" />
+      <br>
+    </a>
+  </div>
+</h1>
+<h3 align="center">
+  SEO-ready multilanguage content engine for Rails.
+</h3>
+<p align="left">
+PostnHost is an open source CMS engine built with Rails, Hotwire, and TailwindCSS. Write, translate, and publish articles with a rich text editor, full version history, and proper SEO that works out of the box.
+</p>
+<p align="left">
+Mount this engine into an existing Rails app, or use the <a href="https://github.com/postnhost/postnhost-app">postnhost-app</a> repository for a pre-configured, self-hosted Rails application.
+</p>
 
-TODO: Delete this and the text below, and describe your gem
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/postnhost`. To experiment with that code, run `bin/console` for an interactive prompt.
+![PostnHost Demo](app/assets/images/postnhost/demo.webp)
+
+## Features
+
+- 📝 **Rich Text Editor** - TipTap-based WYSIWYG editor
+- 🌍 **Multilingual** - Translatable articles, i18n support, and locale-aware SEO metadata
+- 🖼️ **Image Management** - Optimized multisize WebP everywhere
+- 📊 **Version History** - Published version history and rollback options
+- 🤖 **Suggested Articles** - Manual picks plus automatic suggestions from related categories
+- ⏰ **Post Scheduling** - Schedule publication in the chosen timezone
+- 🌐 **Localized SEO** - Localized routes, language switcher, sitemap, and hreflang tags
+- ⚙️ **Settings** - Manage the canonical site URL, pagination, key copy, and assets from the dashboard
+- 🎨 **Customizable Templates** - Override any public view in your host application
+- ⚡ **Hotwire-powered** - Fast, modern UI with Turbo Frames/Streams and Stimulus
+- 👥 **Authors** - Multiple CMS users, author profiles, and per-article co-author bylines
+
+## Table of contents
+
+- [Installation](#installation)
+- [Asset compatibility](#asset-compatibility)
+- [Configuration](#configuration)
+- [Customizing templates](#customizing-templates)
+  - [Replacing favicon](#replacing-favicon)
+  - [Host app i18n](#host-app-i18n-optional)
+  - [Static pages](#static-pages-terms-privacy-etc)
+- [Routes](#routes)
+  - [Production checklist](#production-checklist)
+- [Development](#development)
+- [License](#license)
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+### Requirements
+
+- Ruby 3.4+
+- libvips for image processing
+
+Add PostnHost to your host application's Gemfile:
+
+```ruby
+gem "postnhost"
+```
+
+Run the installer:
+
+```bash
+bundle install
+bin/rails g postnhost:install
+```
+
+This will:
+- Create `config/initializers/postnhost.rb` with configuration options
+- Create `config/initializers/carrierwave.rb` (if not exists)
+- Mount the engine in your routes
+
+Run migrations:
+
+```bash
+bin/rails postnhost:install:migrations
+bin/rails db:migrate
+```
+
+### First-time CMS setup
+
+If there are no users yet, visit **`/blog/onboarding`** to create the first CMS administrator with credentials you choose. This is the default installer path; if you mount the engine somewhere else, open `<mount-path>/onboarding`. The setup flow can add optional sample content after the account is created.
+
+Alternatively, create a CMS user interactively from the terminal:
+
+```bash
+bin/rails g postnhost:user
+```
+
+The generator prompts for the name, email, password, and password confirmation.
+
+## Asset compatibility
+
+PostnHost ships precompiled CSS and a prebundled JavaScript ES module. The engine serves these files through Rails asset helpers, so the host application does not need to compile PostnHost's JavaScript or install its frontend dependencies.
+
+| Host setup | Compatible | How PostnHost integrates |
+| --- | --- | --- |
+| Propshaft | ✅ | The engine registers its packaged builds and images with the host asset pipeline. |
+| Sprockets | ✅ | The engine registers its packaged builds and images for precompilation. |
+| `importmap-rails` | ✅ | The engine bundle is loaded separately from the host import map. No pins are required. |
+| `jsbundling-rails` with esbuild | ✅ | The engine uses its packaged bundle and does not need to be added to the host esbuild entry point. |
+| `cssbundling-rails` or host Tailwind CSS | ✅ | The packaged engine CSS works independently. Use PostnHost host-tailwind mode only when copied views introduce new Tailwind classes. |
+
+A host application must use Propshaft or Sprockets to serve the packaged engine assets, and either pipeline can be paired with import maps or esbuild.
+
+## Configuration
+
+### Initializer (`Postnhost.configure`)
+
+Edit `config/initializers/postnhost.rb`:
+
+```ruby
+Postnhost.configure do |config|
+  # Site defaults used when the matching Dashboard → Settings field is blank
+  # config.site_url = 'https://example.com'
+  # config.public_page_size = 12
+  # config.default_timezone = 'UTC'
+
+  # Optional: required only for AI-assisted translations
+  # config.openai_api_key = 'sk-...'
+  # config.openai_gpt_model = 'gpt-5.6-luna'
+
+  # Required by the generated CarrierWave initializer in production
+  # config.aws_access_key_id = 'AKIA...'
+  # config.aws_secret_access_key = '...'
+  # config.aws_region = 'us-east-1'
+  # config.aws_bucket = 'my-bucket'
+  # config.aws_endpoint_url_s3 = 'https://fly.storage.tigris.dev'
+end
+```
+
+Site URL, pagination, and timezone values are optional defaults; values saved under **Dashboard → Settings** take priority. The OpenAI settings are optional and needed only for AI translations.
+
+The generated CarrierWave initializer uses S3-compatible storage in production. Configure the relevant AWS/S3 values above before deploying; `aws_endpoint_url_s3` is needed only for providers that use a custom endpoint. Alternatively, edit `config/initializers/carrierwave.rb` to use a different production storage backend.
+
+Set dashboard overrides for the canonical site URL and public articles per page under **Dashboard → Settings → Site**. When both site URL sources are blank, public URLs use the incoming request origin.
+
+### Rails credentials (alternative)
+
+Instead of defining values in the initializer, you can add them under `postnhost:` in Rails credentials (`bin/rails credentials:edit`).
+
+```yaml
+postnhost:
+  # For AI translations
+  openai_access_token: ...
+  openai_gpt_model: gpt-5.6-luna
+
+  # For image uploads (S3-compatible)
+  aws_access_key_id: AKIA...
+  aws_secret_access_key: ...
+  aws_region: us-east-1
+  aws_bucket_name: my-bucket
+  aws_endpoint_url_s3: https://s3.us-east-1.amazonaws.com  # or Tigris/other S3-compatible
+```
+
+## Customizing templates
+
+PostnHost includes three public templates: **Default**, **Swiss Editorial**, and **Workspace Journal**. Open **Template** in the CMS, choose a template, preview it, and save the selection.
+
+Copy views to your application for manual/vibecoding customization:
+
+```bash
+bin/rails g postnhost:views --views-scope=minimal
+# or
+bin/rails g postnhost:views --views-scope=full
+```
+
+Host-application copies override the packaged engine views. The CMS selection still controls which template is active.
+
+By default, PostnHost serves packaged engine CSS (`postnhost/application.css`) for zero-setup installs.
+If your copied views introduce new Tailwind utility classes, enable host-tailwind mode so those classes are compiled in the host app.
+
+`--views-scope=minimal`:
+- Copies the Default public content templates under `app/views/postnhost/public/templates/default/`
+- Copies shared public layout partials such as the footer, favicon, logo, and language switcher
+- Excludes internal metadata partials under `content_for/`
+- Keeps SEO/meta internals in the engine by default
+
+`--views-scope=full`:
+- Copies all three public content template sets under `app/views/postnhost/public/templates/`
+- Copies their layouts under `app/views/layouts/postnhost/public/templates/`
+- Copies metadata, structured-data, and SEO partials
+
+### Host Tailwind mode (for custom classes in overridden views)
+
+Enable host-tailwind mode in your host app:
+
+```bash
+bin/rails g postnhost:tailwindcss:install
+bin/dev
+```
+
+This generator creates:
+
+- `app/assets/stylesheets/postnhost/host.tailwind.css`
+- `Procfile.dev` watcher entry:
+  - `postnhost_css: bundle exec rails postnhost:tailwindcss:watch`
+- optional `package.json` scripts (if `package.json` exists):
+  - `postnhost:tailwindcss`
+  - `postnhost:tailwindcss:watch`
+
+Host-tailwind mode builds one combined stylesheet from the engine and host view sources at `app/assets/builds/postnhost/application.css`. That host-owned file transparently overrides the packaged asset with the same logical path; the engine always requests `postnhost/application`. This avoids competing Tailwind builds and lets copied views use ordinary classes such as `bg-red-500` or `md:grid`.
+
+If the host build is absent, Rails uses the packaged engine asset automatically. Both packaged and combined stylesheets are limited to PostnHost layouts through the `data-postnhost` root attribute. You do not need to edit layout tags or prefix Tailwind classes. Host customization requires Tailwind CSS 4.
+
+### Robots.txt sitemap URL (required)
+
+Update the host app `public/robots.txt` so it points to the correct PostnHost sitemap URL.
+
+PostnHost generates `sitemap.xml` automatically from live public articles and pages.
+
+If the engine is mounted at `/`:
+
+```txt
+Sitemap: https://your-domain.com/sitemap.xml
+```
+
+If the engine is mounted at `/blog`:
+
+```txt
+Sitemap: https://your-domain.com/blog/sitemap.xml
+```
+
+Set the canonical production origin under **Dashboard → Settings → Site** or with `config.site_url` so sitemap URLs are generated with the correct host.
+
+### Replacing favicon
+
+PostnHost renders favicon tags from `app/views/layouts/postnhost/_favicon.html.erb` and points to root-level public paths:
+
+- `/favicon.ico`
+- `/icon.svg`
+- `/apple-touch-icon.png`
+- `/site.webmanifest`
+
+Because these are absolute paths, they are served from the **host app** `public/` directory.
+Replace the files in your host app:
+
+```bash
+# From host app root
+cp /path/to/your/favicon.ico public/favicon.ico
+cp /path/to/your/icon.svg public/icon.svg
+cp /path/to/your/apple-touch-icon.png public/apple-touch-icon.png
+cp /path/to/your/site.webmanifest public/site.webmanifest
+```
+
+If you need different markup or paths, run either `postnhost:views` command from the template-customization section, then edit:
+
+- `app/views/layouts/postnhost/_favicon.html.erb`
+
+### Host app i18n (optional)
+
+PostnHost ships with locale files for: `en`, `fr`, `de`, `ja`, `ko`, `pt`, `pl`, `es`, `ru`.
+
+You can use PostnHost without extra i18n setup for a single-locale site. **If you use multiple locales** (localized routes, language switcher, or custom `config/locales/*.yml` files), add this to `config/application.rb`:
+
+```ruby
+config.i18n.default_locale = :en
+config.i18n.available_locales = %i[en fr de ja ko pt pl es ru]
+config.i18n.fallbacks = [:en]
+```
+
+**Required:** `config.i18n.fallbacks = [:en]` (or a map that ultimately falls back to a default language).
 
-Install the gem and add to the application's Gemfile by executing:
+If you want to add more languages, add the locale code to `available_locales` and add `config/locales/<code>.yml`. To scaffold English strings into your host app:
 
 ```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+bin/rails g postnhost:locale it
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+Then translate the values under `postnhost.public` as needed.
+
+### Static pages (Terms, Privacy, etc.)
+
+You can define static public pages directly in your host app under:
+
+- `app/views/postnhost/static_pages/*.html.erb`
+
+You can generate starter templates:
 
 ```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+bin/rails g postnhost:static_pages terms privacy about
 ```
 
-## Usage
+Examples:
+
+- `app/views/postnhost/static_pages/terms.html.erb` → `/blog/terms`
+- `app/views/postnhost/static_pages/privacy.html.erb` → `/blog/privacy`
+- `app/views/postnhost/static_pages/about.html.erb` → `/blog/about`
+
+Link helpers:
+
+```erb
+<%= link_to "Terms", postnhost.public_static_page_path(slug: "terms") %>
+```
+
+## Routes
+
+The engine mounts at `/blog` by default. You can change this in `config/routes.rb`:
+
+```ruby
+mount Postnhost::Engine, at: "/blog"
+```
+
+### Available Public Routes
+
+- `GET /` - Blog index
+- `GET /:locale` - Blog index (localized)
+- `GET /search` - Article search
+- `GET /:locale/search` - Article search (localized)
+- `GET /authors/:slug` - Author show (when author pages are enabled)
+- `GET /:locale/authors/:slug` - Author show (localized, when author pages are enabled)
+- `GET /:category_slug` - Category articles
+- `GET /:locale/:category_slug` - Category articles (localized)
+- `GET /:slug` - Article show or static page
+- `GET /:locale/:slug` - Article show or static page (localized)
+- `GET /preview/:id` - Article preview
+- `GET /sitemap.xml` - XML sitemap
+- `GET /sitemap.xsl` - Sitemap stylesheet
+
+## Production checklist
 
-TODO: Write usage instructions here
+Review these host-application settings before deployment:
+
+- Replace the host app’s favicon and related icon files if needed.
+- Update `public/robots.txt` so its sitemap URL matches the production domain and engine mount path.
+- Review the host app’s static `public/404.html` and `public/500.html` pages.
+- Configure the generated CarrierWave initializer for S3-compatible production storage, or replace it with another storage configuration.
+- If you customize the public templates, copy the required views and enable host Tailwind support when your changes introduce new utility classes.
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+For engine development, use Ruby 4.0.6 and Node.js 24+ as listed in `mise.toml`. Install them with mise, or another version manager, then run:
+
+```bash
+cd postnhost
+bundle install
+yarn install
+```
+
+Run both JS and CSS watchers in one command:
+
+```bash
+yarn dev
+```
+
+### Running tests
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+From the engine root:
 
-## Contributing
+```bash
+bundle install
+yarn install
+bundle exec rake prepare_test_db
+bundle exec rspec
+```
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/postnhost.
+System specs run with Selenium headless by default. Use visible Chrome when needed:
+
+```bash
+SYSTEM_TESTS_BROWSER=1 bundle exec rspec spec/system
+```
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT License](LICENSE).

data/Rakefile

@@ -1,12 +1,72 @@
-# frozen_string_literal: true
+require "bundler/setup"
+require "fileutils"
 
 require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+require_relative "lib/postnhost/css_build"
 
-RSpec::Core::RakeTask.new(:spec)
+css_build = lambda do |watch:|
+  root = __dir__
+  unscoped_path = File.join(root, "app/assets/builds/postnhost/application.unscoped.css")
+  output_path = File.join(root, "app/assets/builds/postnhost/application.css")
+  command = [
+    File.join(root, "node_modules/.bin/tailwindcss"),
+    "-i", File.join(root, "app/assets/stylesheets/application.tailwind.css"),
+    "-o", unscoped_path,
+    "--minify"
+  ]
+  command << "--watch" if watch
 
-require "rubocop/rake_task"
+  Postnhost::CssBuild.run(command:, unscoped_path:, output_path:, watch:)
+end
 
-RuboCop::RakeTask.new
+namespace :css do
+  desc "Build the engine stylesheet"
+  task build: :environment do
+    css_build.call(watch: false)
+  end
 
-task default: %i[spec rubocop]
+  desc "Build the engine stylesheet and watch for changes"
+  task watch: :environment do
+    css_build.call(watch: true)
+  end
+end
+
+# Load dummy app so the Rails `environment` task exists (required by prepare_test_db).
+require_relative "spec/dummy/config/application"
+Rails.application.load_tasks
+
+desc "Prepare dummy app test database"
+task prepare_test_db: :environment do
+  dummy_dir = File.expand_path("spec/dummy", __dir__)
+  engine_migrations_dir = File.expand_path("db/migrate", __dir__)
+  dummy_migrations_dir = File.join(dummy_dir, "db", "migrate")
+  dummy_test_db = File.join(dummy_dir, "storage", "test.sqlite3")
+  dummy_schema = File.join(dummy_dir, "db", "schema.rb")
+
+  FileUtils.mkdir_p(dummy_migrations_dir)
+  FileUtils.rm_f(Dir[File.join(dummy_migrations_dir, "*.rb")])
+  Dir[File.join(engine_migrations_dir, "*.rb")].each do |migration_file|
+    FileUtils.cp(migration_file, dummy_migrations_dir)
+  end
+  FileUtils.rm_f(dummy_test_db)
+  FileUtils.rm_f(dummy_schema)
+
+  system(
+    { "RAILS_ENV" => "test" },
+    "cd #{dummy_dir} && bundle exec rails db:create db:migrate",
+    out: $stdout,
+    err: $stderr
+  ) ||
+    raise("Failed to prepare test database")
+end
+
+begin
+  require "rspec/core/rake_task"
+
+  desc "Run engine specs"
+  RSpec::Core::RakeTask.new(:spec)
+  task spec: :prepare_test_db
+  task default: :spec
+rescue LoadError
+  # rspec-rails is not available in minimal environments.
+end