rivet_cms 0.1.2.pre → 0.3.1

data/COPYING.LESSER

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

data/README.md

@@ -1,10 +1,12 @@
 # RivetCms
-Short description and motivation.
 
-## Usage
-How to use my plugin.
+RivetCms is a headless CMS Rails engine, similar to Strapi. The admin UI is built
+with [Inertia.js](https://inertiajs.com) and React, and ships as a precompiled,
+self-contained bundle — host applications do **not** need Node, Yarn, or any
+JavaScript build step.
 
 ## Installation
+
 Add this line to your application's Gemfile:
 
 ```ruby
@@ -12,23 +14,184 @@ gem "rivet_cms"
 ```
 
 And then execute:
+
 ```bash
 $ bundle
 ```
 
-Or install it yourself as:
+Mount the engine in `config/routes.rb`:
+
+```ruby
+mount RivetCms::Engine => "/cms"
+```
+
+The media library uses Active Storage. If your app doesn't have it yet,
+install it first:
+
+```bash
+$ bin/rails active_storage:install
+```
+
+Run the migrations (the engine appends its own automatically, alongside
+Active Storage's):
+
+```bash
+$ bin/rails db:migrate
+```
+
+`rivet_cms:install:migrations` is also available if you'd rather copy the
+engine's migrations into your app's `db/migrate` than have them run from the
+gem; upgrading the gem then means re-running it to pull new migrations.
+
+Visit `/cms` and create your admin account; that's it. The admin UI's
+JavaScript and CSS are precompiled into the gem (`app/assets/builds/`) and
+served through the asset pipeline (Propshaft or Sprockets), so no frontend
+tooling is required in the host app.
+
+## Authentication
+
+Out of the box RivetCMS handles sign-in itself: the first visit creates the
+first admin account, and a Users page invites more. CE has no roles, so every
+signed-in user can do everything; role and record-scoped permissions are a
+RivetCMS Pro feature. New users are invited with a copyable sign-in link
+(signed, expires in 3 days, dies once a password is set), so no mail delivery
+is required. There is no self-registration, and users are deactivated rather
+than deleted.
+
+Apps with their own authentication plug it in instead, which disables all of
+the above (no engine login routes, no Users page; manage people in your own
+admin):
+
+```ruby
+RivetCms.configure do |config|
+  config.authenticate = ->(controller) { controller.user_signed_in? }
+  config.current_user = ->(controller) { controller.current_user }
+  config.login_path   = "/login"
+  config.logout_path  = "/logout"
+end
+```
+
+## Starter content types
+
+RivetCMS ships content-type templates (blog, pages, events, FAQ, team,
+testimonials, site settings) so a fresh install isn't a blank slate:
+
+```bash
+$ bin/rails rivet_cms:templates                 # list available templates
+$ bin/rails rivet_cms:seed                      # load all of them
+$ bin/rails rivet_cms:seed TEMPLATES=blog,pages # load a subset
+$ bin/rails rivet_cms:seed ORG=example.com      # into a specific org, by domain
+```
+
+Templates are a starting point, not a fixture: they create content types,
+fields, and components you then edit freely. Loading is idempotent, re-running
+updates the same records by slug rather than duplicating them.
+
+## Media processing (optional system dependencies)
+
+The media library generates thumbnails through Active Storage. What renders
+depends on which system binaries the host has installed; everything degrades
+gracefully to a file-type icon when a binary is missing:
+
+| Binary | Install (Debian/Ubuntu) | Install (macOS) | Enables |
+|---|---|---|---|
+| libvips (recommended) | `apt install libvips` | `brew install vips` | Image thumbnails (resized variants) |
+| poppler | `apt install poppler-utils` | `brew install poppler` | PDF thumbnails (first page) |
+| ffmpeg | `apt install ffmpeg` | `brew install ffmpeg` | Video thumbnails (first frame) |
+
+None are hard dependencies: uploads, storage, and delivery work without them.
+Without poppler or ffmpeg, PDFs and videos show a type icon instead of a
+preview. libvips is the one you really want: without it image thumbnail
+requests fail and grid cells stay on their neutral placeholder (full-size
+originals still serve fine everywhere else). Thumbnails are processed lazily
+on first request and cached by Active Storage.
+
+## Reading content from Ruby
+
+Host apps can read CMS content directly — no HTTP round-trip — with the same
+semantics and options as the delivery API (published-only lists, draft-leak
+rules, constant-query preloading):
+
+```ruby
+# Lists: sort, date-range filters, pagination, populate, sparse fields
+posts = RivetCms.entries("posts", sort: "-published_at", page: 1, per_page: 10)
+posts = RivetCms.entries("posts", populate: %w[author categories])   # or populate: :all
+events = RivetCms.entries("events", filters: { "starts_at" => { gte: Date.today } })
+
+# Single entries by slug (nil when missing or unpublished)
+post = RivetCms.entry("posts", "hello-world", populate: :all)
+post = RivetCms.entry("posts", "hello-world", preview: true)   # draft when present
+
+# Single-type content
+settings = RivetCms.single("site-settings")
+
+# Entries expose field values as methods, [] access, or the raw hash
+post.title            # data access (post[:title] and post.data also work)
+post.author.name      # populated references are nested entries
+post.to_h             # same shape as the API JSON
+posts.total_pages     # lists carry pagination numbers
+```
+
+The organization defaults to `RivetCms::Current.organization` (or the default
+organization); pass `organization:` explicitly in jobs and scripts. Unknown
+option values — sort/filter/populate/fields keys — raise
+`RivetCms::ContentQuery::Error`, mirroring the API's 400s.
+
+## Deleting content
+
+Deleting is recoverable by default. Removing a content type or an entry moves
+it to a trash: it disappears from the admin and stops being served by the
+delivery API, but every revision and value is kept, and restoring brings it
+all back. Both trashes are reachable from their list pages.
+
+Permanent deletion lives only inside the trash, so removing and destroying are
+always two deliberate steps. Purging a content type additionally requires
+typing its name, since it destroys every entry of that type; purging a single
+entry asks for a plain confirmation naming it.
+
+```ruby
+# Restoring is also available from the console
+RivetCms::ContentType.with_discarded.find_by(slug: "articles").undiscard!
+RivetCms::Document.with_discarded.find_by(slug: "hello-world").undiscard!
+```
+
+A trashed type or entry keeps its slug reserved, so restoring can never
+collide with something created in the meantime.
+
+## Development
+
+The frontend lives in `app/javascript` (React + Inertia pages) and is bundled
+with esbuild; styles are Tailwind CSS 4 + daisyUI. To work on the engine:
+
 ```bash
-$ gem install rivet_cms
+$ yarn install
+$ bin/dev        # runs the dummy app plus JS/CSS watchers
+```
+
+Rebuild the production bundles (committed to the repo so the gem stays
+self-contained):
+
+```bash
+$ yarn build && yarn build:css
+```
+
+Run the test suite:
+
+```bash
+$ bundle exec rspec
 ```
 
 ## Contributing
+
 Contribution directions go here.
 
 ## License
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
-
-## Acknowledgments
 
-This project includes code adapted from or inspired by:
+RivetCMS is licensed under the GNU Lesser General Public License v3.0 or
+later (LGPL-3.0-or-later). The full text is in [`COPYING.LESSER`](COPYING.LESSER)
+(the additional permissions) and [`COPYING`](COPYING) (the GPLv3 it builds on).
 
-- [Spree Commerce](https://github.com/spree/spree) - Route handling pattern for extensible engines (MIT License)
+In short: you can use RivetCMS in your own application, including a closed-
+source or commercial one, without that application becoming subject to the
+LGPL. If you modify RivetCMS itself and distribute that modified version,
+those modifications must be shared under the same license.