postnhost 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58a5e825dc2b90b41ca5409f379a5ef6257b6d05de4cec3e7dc517d52cd045fd
-  data.tar.gz: ffae44f7bc9a560d21a8d910b16ff7e4bc7aac14819ebe01b9e28f101b2012da
+  metadata.gz: f12e20da143bbf828f95af42951dcfc1bbce4e9152dd47630ea8a668b73b8a6b
+  data.tar.gz: 8ae19423f07e68ec8fef6ba7a4014751b25b658e218a939bf802157247b96c05
 SHA512:
-  metadata.gz: 6ea72f1636e28368c812810ce70784a4a0067477596b01d7655532d667df81b2016186a6bea73fc639cd3a07bbaa376f0a2f4ba211bba02cbd09f12fa60594c0
-  data.tar.gz: 5f8cf9da3f29af73e5ab9e8d612762ee16220f9acda35eac2bf8386ff5a08b68374812d682a5fb68e2af220840fa60a0ef12993c78f03f448d5d4d4115c76702
+  metadata.gz: c40643ed0fd03ec5bc35a717c08a50a7942f9b64df50e397ab4de7217a46090c60d3ae2f25684fb8c5629bb264a1fb4ca87ab6119a819512db90eb84d0f6b2ff
+  data.tar.gz: af8cd76fde91eaad7ac5c175721ca1b7b5a26a80caad882fcfe404ce5bd486252a57dd3681ed108fa51d90d8c500c969e05863b234c4034804502937971186db

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to PostnHost are documented in this file.
+
+## [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.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,365 @@
-# 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)
+- [Manual configuration](#manual-configuration)
+- [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
 
-Install the gem and add to the application's Gemfile by executing:
+### 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
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+bin/rails g postnhost:views --views-scope=minimal
+# or
+bin/rails g postnhost:views --views-scope=full
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+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
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+bin/rails g postnhost:tailwindcss:install
+bin/dev
 ```
 
-## Usage
+This generator creates:
+
+- `postnhost.tailwind.config.js`
+- `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`
+
+When host-tailwind mode files are present, PostnHost layouts automatically include `postnhost/host.css` after `postnhost/application.css`.
+You do not need to edit layout tags.
+
+### 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
+```
 
-TODO: Write usage instructions here
+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).
+
+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
+bin/rails g postnhost:locale it
+```
+
+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
+bin/rails g postnhost:static_pages terms privacy about
+```
+
+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
+
+## Manual configuration
+
+Some parts must still be configured manually in code:
+
+- Favicons
+- Robots.txt
+- Error pages 404/500 etc.
 
 ## 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,44 @@
-# frozen_string_literal: true
+require "bundler/setup"
+require "fileutils"
 
 require "bundler/gem_tasks"
-require "rspec/core/rake_task"
 
-RSpec::Core::RakeTask.new(:spec)
+# Load dummy app so the Rails `environment` task exists (required by prepare_test_db).
+require_relative "spec/dummy/config/application"
+Rails.application.load_tasks
 
-require "rubocop/rake_task"
+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")
 
-RuboCop::RakeTask.new
+  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)
 
-task default: %i[spec rubocop]
+  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