andromeda_cms 0.1.0

data/Cargo.toml

@@ -0,0 +1,12 @@
+# rb-sys resolves crate metadata from the gem root, so the extension lives in a
+# workspace rather than standing alone under ext/.
+[workspace]
+members = ["ext/andromeda_cms"]
+resolver = "2"
+
+# Profiles only take effect at the workspace root; in the member crate Cargo
+# ignored them, which left Windows builds unstripped at four times the size.
+[profile.release]
+opt-level = 3
+strip = true
+lto = true

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LIMHAUS Inc.
+
+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/README.md

@@ -0,0 +1,276 @@
+# Andromeda
+
+Astro-compatible content collections for Ruby on Rails.
+
+[Documentation](https://www.andromedacms.dev/docs) · [Changelog](CHANGELOG.md)
+
+Copy the `.md` and `.mdx` files from an [Astro](https://astro.build) project
+into `app/content/`, and Andromeda validates their frontmatter against a schema
+and renders them as ordinary Rails pages. The heavy work — parsing Markdown and
+MDX and expanding components — happens once at deploy time; requests only read
+the result.
+
+> **Status: pre-release.** The API is not stable yet.
+
+## Why
+
+Adding a blog, docs or a marketing site to a Rails app has usually meant one of
+three things: standing up a separate Astro or Next.js project, installing a CMS
+gem with its own tables and admin screens, or wiring up a headless CMS over
+HTTP. Andromeda takes Astro's content model — collections, schemas, MDX
+components — and makes it a gem, so the content lives next to the application
+that already has your authentication, your layouts and your deploy pipeline.
+
+### Files are the interface
+
+Those three options all put content behind a database and a screen. That made
+sense while people were the only ones writing. They are not any more: much of
+the writing, editing and restructuring now happens with an assistant in the
+loop, and an assistant is good at exactly one thing here — reading and writing
+files in a repository it can already see. Pointing it at a CMS means first
+building it an API or an MCP server, giving that its own authentication, and
+keeping it in sync with the schema. A second system, to serve the first.
+
+Content as files needs none of that. Adding a post is adding a file, editing
+one is an edit, removing one is `rm`. The change arrives as a diff, is reviewed
+like any other, and ships with the deploy that carried it — and the tool doing
+the writing needs no integration at all, because it already has the repository.
+Of everything in Astro's design, this is the part that looks most like where
+things are going.
+
+### Alongside Astro, not against it
+
+I like [Astro](https://astro.build), and I have a great deal of respect for the
+team behind it. For a static site I still reach for it. But when a site needs
+sessions, forms, background jobs and a database, I want Rails. Andromeda exists
+so that this is not a choice between the two: the collection stays the same
+directory of files, parsed by the same engine Astro 7 uses, and moving it into
+Rails is a copy.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "andromeda_cms"
+```
+
+```bash
+bundle install
+bin/rails generate andromeda:install
+```
+
+Ruby 3.2+ and Rails 8.0+. The gem ships precompiled binaries for common
+platforms, so no Rust toolchain is needed to install it.
+
+## Getting started
+
+```bash
+bin/rails generate andromeda:collection blog title:string pub_date:date
+```
+
+That writes an entry class, a controller, views, a route and a first post:
+
+```ruby
+# app/models/content/blog.rb
+module Content
+  class Blog < Andromeda::Entry
+    collection :blog, base: "app/content/blog", pattern: "**/*.{md,mdx}"
+
+    attribute :title, :string
+    attribute :pub_date, :date
+
+    # scope :published, -> { where(draft: false) }
+  end
+end
+```
+
+```ruby
+# app/controllers/blog_controller.rb
+class BlogController < ApplicationController
+  def index
+    @entries = Content::Blog.all.order(pub_date: :desc)
+  end
+
+  def show
+    @entry = Content::Blog.find(params[:slug])
+  end
+end
+```
+
+```erb
+<%# app/views/blog/show.html.erb %>
+<article>
+  <h1><%= @entry.title %></h1>
+  <%= andromeda_content @entry %>
+</article>
+```
+
+From there it is your code. A typical next step is to make fields mandatory,
+add a draft flag, and add a table of contents:
+
+```ruby
+attribute :title, :string, required: true
+attribute :pub_date, :date, required: true
+attribute :draft, :boolean, default: false
+
+scope :published, -> { where(draft: false) }
+```
+
+```erb
+<%= andromeda_toc @entry %>
+```
+
+An unknown slug raises `Andromeda::EntryNotFound`, which Rails answers with a
+404.
+
+Pages are ordinary Rails, so layouts, `current_user`, CSRF tokens, caching and
+authorization all behave exactly as they normally do.
+
+## Content
+
+```markdown
+---
+title: Hello world
+pub_date: 2026-09-01
+tags: [rails, astro]
+---
+
+## Getting started
+
+Ordinary GFM Markdown, with smart punctuation and syntax highlighting.
+```
+
+Frontmatter is validated against the entry class: a missing `title` or an
+unparseable date fails the build with the file name and line number, rather
+than surfacing as `nil` in a view.
+
+### MDX components
+
+MDX components map to Rails partials — no ViewComponent dependency:
+
+```mdx
+import Callout from 'content_components/callout';
+
+<Callout type="tip" title="Note">
+  The body is **Markdown** too.
+</Callout>
+```
+
+```erb
+<%# app/views/content_components/_callout.html.erb %>
+<aside class="callout callout--<%= local_assigns.fetch(:type, "note") %>">
+  <% if local_assigns[:title] %><p class="callout__title"><%= title %></p><% end %>
+  <%= content %>
+</aside>
+```
+
+Props arrive as locals (`camelCase` becomes `snake_case`), the tag's children
+arrive as `content`, and `<Fragment slot="header">` becomes a `header` local.
+`bin/rails generate andromeda:component Callout type title` writes the stub.
+
+### Images
+
+Put an image next to the entry and reference it relatively:
+
+```
+app/content/blog/my-post/
+├── index.md
+└── cover.png
+```
+
+```markdown
+![Cover](./cover.png)
+```
+
+Referenced images are copied into `app/assets/builds/andromeda/` during the
+build and served, digest-stamped, by the asset pipeline. Images the app
+already ships (`app/assets/images/logo.png`, written as `logo.png`) resolve
+through the pipeline too; anything under `public/` or on another host is left
+untouched. Declare a frontmatter image with `attribute :hero_image, :image`
+and render it with `andromeda_image_url`.
+
+## Development and deployment
+
+```
+development:  request → entry is converted on demand when its source changed
+production:   deploy  → andromeda:build writes .andromeda/, requests only read it
+```
+
+There is no watcher process to run: in development a file is converted the
+first time something asks for it after it changes. In production the parser
+never runs while serving a request, and an unbuilt entry raises an error that
+names the fix instead of silently converting.
+
+`andromeda:build` is hooked into `assets:precompile`, so the Rails 8 Dockerfile
+(and Kamal, and Heroku) already runs it. `.andromeda/` is a build artifact:
+the installer adds it to `.gitignore` and `.dockerignore`.
+
+| Task | What it does |
+|------|--------------|
+| `andromeda:build` | Convert every entry into `.andromeda/` (runs during `assets:precompile`) |
+| `andromeda:check` | Report schema problems, missing components and non-snake_case keys; writes nothing (for CI) |
+| `andromeda:fix` | Rewrite non-snake_case frontmatter keys in place |
+| `andromeda:clobber` | Remove `.andromeda/` (runs during `assets:clobber`) |
+
+## Migrating from Astro
+
+```bash
+bin/rails generate andromeda:import_astro ../my-astro-site
+```
+
+It copies `src/content` and `src/assets`, rewrites frontmatter keys to
+snake_case and MDX imports to partial paths, converts `content.config.ts` into
+entry classes, generates stubs for the components your content imports, and
+prints what still needs a human. `--dry-run` shows the plan without writing.
+
+Astro's own [`examples/blog`](https://github.com/withastro/astro/tree/main/examples/blog)
+imports and renders unchanged; that is a test in this repository.
+
+## Compatibility
+
+Andromeda targets Astro 7 and later and uses
+[Sätteri](https://github.com/bruits/satteri) — the Markdown and MDX engine
+Astro 7 uses by default — so content is parsed by the same engine that parsed
+it in Astro. Heading ids use github-slugger, `headings` has the same shape as
+Astro's `render()`, and entry ids follow Astro's `glob()` loader rules.
+
+The goal is that content copied from an Astro project loads without errors and
+displays. Byte-identical output is a non-goal: syntax highlighting uses Rouge
+rather than Shiki (same markup shape, approximate colours), and images are
+served by the asset pipeline rather than Astro's image service.
+
+Not supported: Astro's pages and routing, islands and `client:*` directives,
+remark/rehype plugins, and arbitrary JavaScript in MDX expressions (literals,
+`{frontmatter.x}` and comments are evaluated; anything else is an error rather
+than a silent drop).
+
+## Development
+
+```bash
+bin/setup            # or: bundle install
+bundle exec rake     # compiles the Rust extension, then runs the tests
+bundle exec rake test:corpus  # after test/fetch_corpus.sh: parse ~370 real Astro files
+```
+
+## Troubleshooting
+
+**`ArgumentError: wrong number of arguments (given 2, expected 1)` from `JSON.parse`.**
+Not this gem: Rails 8.1 calls `JSON.parse` with a positional options hash, which
+version 3 of the `json` gem no longer accepts, and decrypting a session cookie
+hits that path — so pages fail only once a session exists. Pin the `json` gem
+until Rails ships a fix:
+
+```ruby
+# Gemfile
+gem "json", "~> 2.9"
+```
+
+## Contributing
+
+Bug reports are welcome; patches are not. Andromeda is open source but not open
+contribution — see [CONTRIBUTING.md](CONTRIBUTING.md) for why, and for what a
+useful bug report contains.
+
+## License
+
+Copyright (c) 2026 [LIMHAUS Inc.](https://www.limhaus.com/). Released under the [MIT License](LICENSE.txt).

data/ext/andromeda_cms/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "andromeda_cms"
+version = "0.1.0"
+edition = "2021"
+publish = false
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+magnus = "0.8"
+# Sätteri is the Markdown/MDX engine Astro 7 uses by default, so parsing here
+# matches what the content author saw in Astro. It is pre-1.0: versions are
+# pinned and a corpus regression test guards upgrades.
+satteri-ast = "0.5"
+satteri-arena = "0.3"
+satteri-pulldown-cmark = "0.6"
+serde_json = "1"

data/ext/andromeda_cms/extconf.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require "mkmf"
+require "rb_sys/mkmf"
+
+create_rust_makefile("andromeda_cms/andromeda_cms")

data/ext/andromeda_cms/src/errors.rs

@@ -0,0 +1,55 @@
+//! Converts Sätteri parse failures into the `Andromeda::*` exception classes
+//! that Ruby callers already know about (see `lib/andromeda/errors.rb`).
+//!
+//! Rust raises the real Ruby classes directly (rather than a generic
+//! `RuntimeError`) so `rescue Andromeda::SyntaxError` works without the Ruby
+//! wrapper having to re-wrap every native call. The classes are looked up by
+//! name through `Ruby#eval` instead of being cached, because construction
+//! only happens on the (rare) error path — the ~0.3ms/file hot path never
+//! touches this module.
+
+use magnus::{kwargs, Class, Error, ExceptionClass, Ruby};
+use satteri_arena::LineIndex;
+use std::any::Any;
+
+/// Builds an `Andromeda::SyntaxError` from a Sätteri MDX error.
+///
+/// Sätteri reports errors as `(byte_offset, message)` pairs with no line/
+/// column of their own, so we re-derive them from the same `LineIndex` the
+/// parser itself uses (1-based line/column, matching `ArenaNode`'s fields).
+///
+/// `path` is intentionally not set here: the native layer has no notion of
+/// "which file is this" — `Andromeda::Parser.parse` (Ruby) re-raises with
+/// `path:` attached once it knows it.
+pub fn syntax_error(
+    ruby: &Ruby,
+    source: &str,
+    offset: usize,
+    message: &str,
+) -> Result<Error, Error> {
+    let index = LineIndex::from_source(source);
+    let mut cursor = index.cursor();
+    let (line, column) = cursor.offset_to_line_col(offset as u32);
+
+    let class: ExceptionClass = ruby.eval("Andromeda::SyntaxError")?;
+    let exception =
+        class.new_instance((message, kwargs!(ruby, "line" => line, "column" => column)))?;
+    Ok(Error::from(exception))
+}
+
+/// Builds an `Andromeda::ParserError` from a caught Rust panic payload.
+///
+/// Sätteri is pre-1.0 (see Cargo.toml comment); a panic here must not abort
+/// the whole Ruby process, so callers wrap the parse in `catch_unwind` and
+/// hand the payload to this function instead of letting it unwind past the
+/// FFI boundary (which would be undefined behavior).
+pub fn parser_error(ruby: &Ruby, payload: &(dyn Any + Send)) -> Result<Error, Error> {
+    let message = payload
+        .downcast_ref::<&str>()
+        .map(|s| s.to_string())
+        .or_else(|| payload.downcast_ref::<String>().cloned())
+        .unwrap_or_else(|| "the native Markdown/MDX parser panicked".to_string());
+
+    let class: ExceptionClass = ruby.eval("Andromeda::ParserError")?;
+    Ok(Error::new(class, message))
+}

data/ext/andromeda_cms/src/lib.rs

@@ -0,0 +1,143 @@
+//! Native Markdown/MDX parser for the `andromeda_cms` gem.
+//!
+//! Wraps Sätteri (the Rust engine Astro 7+ uses by default) to extract an
+//! mdast tree as JSON. See `Cargo.toml` for why Sätteri.
+//!
+//! Parsing happens fully in Rust; the mdast tree crosses the FFI boundary as
+//! a single JSON string rather than as nested Ruby objects, because building
+//! Ruby `Hash`/`Array` objects node-by-node through the Ruby C API is far
+//! slower than one `serde_json::to_string` + one `JSON.parse` on the Ruby
+//! side (roughly comparable either way; JSON avoids also
+//! having to hold the GVL while walking the arena).
+
+mod errors;
+mod nodes;
+
+use magnus::{function, prelude::*, Error, Ruby};
+use satteri_pulldown_cmark::{Options, DEFAULT_OPTIONS};
+use std::panic;
+
+/// Identifies the engine backing `Parser.parse`, so host apps and tests can
+/// assert on it without depending on Sätteri internals directly.
+fn parser_backend() -> String {
+    "satteri".to_string()
+}
+
+fn options_for(mdx: bool) -> Options {
+    // satteri-pulldown-cmark's own MDX_OPTIONS constant is just
+    // `DEFAULT_OPTIONS | ENABLE_MDX` (arena_build.rs); it is not used
+    // directly below because ENABLE_SMART_PUNCTUATION also needs adding to
+    // both the MDX and non-MDX cases. DEFAULT_OPTIONS already turns on GFM (tables,
+    // strikethrough, task lists, autolinks), footnotes, math, and YAML
+    // frontmatter, matching Astro's `markdown.gfm` default of `true`
+    // (`@astrojs/markdown-satteri`'s `features: { gfm: gfm !== false, ... }`).
+    //
+    // Deliberately NOT enabled, to stay compatible with what Astro actually
+    // ships: ENABLE_HEADING_ATTRIBUTES (remark doesn't parse `# H {#id}`,
+    // and Astro derives heading ids via a separate github-slugger pass, not
+    // Sätteri), ENABLE_DIRECTIVE / ENABLE_DEFINITION_LIST / ENABLE_SUPERSCRIPT
+    // / ENABLE_SUBSCRIPT (no remark-directive/remark-supersub equivalent in
+    // Astro's default pipeline).
+    //
+    // ENABLE_SMART_PUNCTUATION:
+    // Astro enables remark-smartypants unconditionally
+    // (packages/internal-helpers/src/markdown.ts's `markdownConfigDefaults`),
+    // but DEFAULT_OPTIONS does *not*
+    // include it -- confirmed by reading satteri-pulldown-cmark's
+    // arena_build.rs (`DEFAULT_OPTIONS` bitset has no
+    // `ENABLE_SMART_PUNCTUATION`). It has to be turned on explicitly here so
+    // straight quotes/dashes/ellipses in Markdown text get the same
+    // curly-quote/em-dash/ellipsis substitution Astro's output has by
+    // default; `Options::ENABLE_SMART_PUNCTUATION` is itself just
+    // `ENABLE_SMART_QUOTES | ENABLE_SMART_DASHES | ENABLE_SMART_ELLIPSES`
+    // (satteri-pulldown-cmark's lib.rs), which is exactly what
+    // retext-smartypants' default options transform.
+    let base = DEFAULT_OPTIONS | Options::ENABLE_SMART_PUNCTUATION;
+
+    if mdx {
+        base | Options::ENABLE_MDX
+    } else {
+        base
+    }
+}
+
+/// `Andromeda::Parser.native_parse(source, mdx)` -> mdast JSON string.
+///
+/// Ruby-facing errors: `Andromeda::SyntaxError` (source could not be parsed,
+/// carries line/column) or `Andromeda::ParserError` (Sätteri itself panicked).
+/// See `lib/andromeda/parser.rb` for the public wrapper that attaches `path`.
+///
+/// Nesting is capped at `MAX_DEPTH` (see there for why).
+/// Deeper trees are rejected as a syntax error instead of converted.
+///
+/// Converting the tree to JSON, and rendering it to HTML on the Ruby side,
+/// are both recursive over nesting depth. A few thousand nested `>` or
+/// `<div>` overflow the native stack, and on a Ruby thread other than the
+/// main one -- which is where Puma serves development requests -- the stack
+/// is small enough that 5,000 levels already fail. Real content nests a handful of levels; 256 leaves ample room for it
+/// while keeping every recursive step far from any stack limit.
+const MAX_DEPTH: usize = 256;
+
+/// Longest run of a single `*` or `_` accepted.
+///
+/// Sätteri resolves emphasis recursively while parsing, before there is a
+/// tree for `MAX_DEPTH` to inspect, so its depth has to be bounded from the
+/// source instead. On a Puma thread a run of about 50,000 exhausts the
+/// stack; no real document has a run anywhere near 10,000.
+const MAX_DELIMITER_RUN: usize = 10_000;
+
+/// Byte offset where the first over-long `*`/`_` run starts, if any.
+fn overlong_delimiter_run(source: &str) -> Option<usize> {
+    let bytes = source.as_bytes();
+    let mut start = 0;
+    for (index, &byte) in bytes.iter().enumerate() {
+        if index == 0 || byte != bytes[index - 1] {
+            start = index;
+        }
+        if (byte == b'*' || byte == b'_') && index - start + 1 > MAX_DELIMITER_RUN {
+            return Some(start);
+        }
+    }
+    None
+}
+
+fn rb_native_parse(ruby: &Ruby, source: String, mdx: bool) -> Result<String, Error> {
+    if let Some(offset) = overlong_delimiter_run(&source) {
+        let message = format!("a run of more than {MAX_DELIMITER_RUN} `*` or `_` characters is nested too deeply to parse");
+        return Err(errors::syntax_error(ruby, &source, offset, &message)?);
+    }
+
+    let parsed = panic::catch_unwind(panic::AssertUnwindSafe(|| {
+        satteri_pulldown_cmark::parse(&source, options_for(mdx))
+    }));
+
+    let (arena, mdx_errors) = match parsed {
+        Ok(pair) => pair,
+        // Sätteri is pre-1.0 (see Cargo.toml); a panic must not abort the
+        // whole Ruby process, so it is converted into a normal exception.
+        Err(payload) => return Err(errors::parser_error(ruby, payload.as_ref())?),
+    };
+
+    if let Some((offset, message)) = mdx_errors.first() {
+        return Err(errors::syntax_error(ruby, &source, *offset, message)?);
+    }
+
+    if let Some(id) = nodes::first_node_deeper_than(&arena, 0, MAX_DEPTH) {
+        let offset = arena.get_node(id).start_offset as usize;
+        let message = format!("content is nested more than {MAX_DEPTH} levels deep");
+        return Err(errors::syntax_error(ruby, &source, offset, &message)?);
+    }
+
+    let json = nodes::node_to_json(&arena, 0);
+    serde_json::to_string(&json)
+        .map_err(|e| Error::new(ruby.exception_runtime_error(), e.to_string()))
+}
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let namespace = ruby.define_module("Andromeda")?;
+    let parser = namespace.define_module("Parser")?;
+    parser.define_singleton_method("backend", function!(parser_backend, 0))?;
+    parser.define_singleton_method("native_parse", function!(rb_native_parse, 2))?;
+    Ok(())
+}