ro 4.4.0 → 5.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b56a7cf51b2b6e2140b3be71875fe284e77a59d0e7fa108fd45d39369aba51b
-  data.tar.gz: 02da6783adba57026d22c2e95841ad3b3acc4979c538bd86896b7f293037178b
+  metadata.gz: ce865a6e0af863e98426c6a5822464695d0baf15ab6ebc1b7e0acdbf88cdc51a
+  data.tar.gz: 8e20b5b872b2aef30ae6ff524d287266d8d720ff7ffb63c22513160aab773b72
 SHA512:
-  metadata.gz: b704d4f58a18df10308884c353dc05293d294d46ddfb46b8241e5047691500dcf5471f5dac5522a8126e59885c61b49fd03deba036e54db6f2191145706f0450
-  data.tar.gz: 3bcf32a9c1096c33c898b582f4d038625771c44203ce49792017d07b097285327ce6e90f0c3136bfdda1e185c0d826a50eefbf377dfd2e6e9fc126b8bfed80bf
+  metadata.gz: 8b32bd17c787b5969801e7fb72146802aaf8758a0003994eb5363b821508fab65128b4d7dfe614c5df2fee1a5f507cf4c88aaeaa37df4799e11303b87e486600
+  data.tar.gz: a6dfe0e278908e892f8c79c15003c9b0ccfe7eadde98efb086b0a8d44f4f59716a81bd76c9bc4dd6af854b5b24ffb34ae75a2801c752e66995e0411a7ca36401

data/Gemfile.lock

@@ -1,14 +1,17 @@
 PATH
   remote: .
   specs:
-    ro (4.2.1)
-      ak47 (~> 0.2)
-      image_size (~> 3.0)
+    ro (4.4.1)
+      ak47 (~> 0.2.5)
+      front_matter_parser (~> 1.0)
+      image_size (~> 3.4)
       kramdown (~> 2.4, >= 2.4.0)
       kramdown-parser-gfm (~> 1.1, >= 1.1.0)
       map (~> 6.6, >= 6.6.0)
+      nokogiri (~> 1)
+      rinku (~> 2.0)
       rouge (~> 4.1, >= 4.1.1)
-      webrick (~> 1.8.1)
+      webrick (~> 1.9, >= 1.9.1)
 
 GEM
   remote: https://rubygems.org/
@@ -17,17 +20,18 @@ GEM
       guard (~> 0.10.0)
       shell_tools (~> 0.1.0)
       smart_colored
-    ffi (1.17.0)
-    ffi (1.17.0-aarch64-linux-gnu)
-    ffi (1.17.0-aarch64-linux-musl)
-    ffi (1.17.0-arm-linux-gnu)
-    ffi (1.17.0-arm-linux-musl)
-    ffi (1.17.0-arm64-darwin)
-    ffi (1.17.0-x86-linux-gnu)
-    ffi (1.17.0-x86-linux-musl)
-    ffi (1.17.0-x86_64-darwin)
-    ffi (1.17.0-x86_64-linux-gnu)
-    ffi (1.17.0-x86_64-linux-musl)
+    ffi (1.17.2)
+    ffi (1.17.2-aarch64-linux-gnu)
+    ffi (1.17.2-aarch64-linux-musl)
+    ffi (1.17.2-arm-linux-gnu)
+    ffi (1.17.2-arm-linux-musl)
+    ffi (1.17.2-arm64-darwin)
+    ffi (1.17.2-x86-linux-gnu)
+    ffi (1.17.2-x86-linux-musl)
+    ffi (1.17.2-x86_64-darwin)
+    ffi (1.17.2-x86_64-linux-gnu)
+    ffi (1.17.2-x86_64-linux-musl)
+    front_matter_parser (1.0.1)
     guard (0.10.0)
       ffi (>= 0.5.0)
       thor (~> 0.14.6)
@@ -37,12 +41,34 @@ GEM
     kramdown-parser-gfm (1.1.0)
       kramdown (~> 2.0)
     map (6.6.0)
+    mini_portile2 (2.8.8)
+    nokogiri (1.18.8)
+      mini_portile2 (~> 2.8.2)
+      racc (~> 1.4)
+    nokogiri (1.18.8-aarch64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.18.8-aarch64-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.18.8-arm-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.18.8-arm-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.18.8-arm64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.18.8-x86_64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.18.8-x86_64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.18.8-x86_64-linux-musl)
+      racc (~> 1.4)
+    racc (1.8.1)
     rexml (3.3.9)
+    rinku (2.0.6)
     rouge (4.4.0)
     shell_tools (0.1.2)
     smart_colored (1.1.1)
     thor (0.14.6)
-    webrick (1.8.2)
+    webrick (1.9.1)
 
 PLATFORMS
   aarch64-linux-gnu

data/MIGRATION.md

@@ -0,0 +1,320 @@
+# Ro v5.0 Asset Structure Migration Guide
+
+## Overview
+
+Ro v5.0 introduces a simplified asset directory structure that reduces nesting depth and makes assets easier to understand and manage.
+
+### Automatic Warning System
+
+Ro v5.0 automatically detects when you're using old structure data and warns you on stderr:
+
+```
+⚠️  WARNING: Old Ro asset structure detected!
+
+This Ro root contains assets in the OLD structure format:
+  • identifier/attributes.yml
+  • identifier/assets/
+
+Ro v5.0 uses a simplified NEW structure:
+  • identifier.yml
+  • identifier/
+
+Collections will NOT automatically discover old-structure nodes.
+
+To migrate your data, run:
+  ro migrate /path/to/your/data
+```
+
+**This warning does NOT stop your program** - it's informational to help you know you need to migrate. The warning appears once per root directory when `Ro::Root.new` is called.
+
+### Old Structure (v4.x)
+```
+posts/
+  sample-post/
+    attributes.yml       # Metadata file INSIDE node directory
+    assets/             # Assets subdirectory
+      image.jpg
+      document.pdf
+```
+
+### New Structure (v5.0)
+```
+posts/
+  sample-post.yml       # Metadata file at COLLECTION level (moved out)
+  sample-post/          # Node directory (same location)
+    assets/             # Assets subdirectory (SAME location as before!)
+      image.jpg
+      document.pdf
+```
+
+## Benefits
+
+- **Simpler**: One less level of nesting
+- **Clearer**: Metadata file and assets directory are siblings, not parent/child
+- **Faster**: Easier to locate assets by identifier
+- **More Intuitive**: Structure is self-documenting
+
+## Migration Tool
+
+Ro v5.0 includes a migration tool to automate the conversion from old to new structure.
+
+### Basic Usage
+
+```bash
+# Preview migration (dry run)
+./bin/ro migrate --dry-run /path/to/your/ro/root
+
+# Run migration with backup (recommended)
+./bin/ro migrate /path/to/your/ro/root
+
+# Run migration without backup (not recommended)
+./bin/ro migrate --no-backup /path/to/your/ro/root
+```
+
+### Options
+
+- `--dry-run`, `-d`: Preview changes without making them
+- `--backup`, `--no-backup`, `-b`: Create backup before migrating (default: true)
+- `--verbose`, `-v`: Show detailed progress
+- `--force`, `-f`: Force migration even if new structure detected
+- `--help`, `-h`: Show help message
+
+### Migration Process
+
+The migration tool:
+
+1. **Validates** the structure to detect old/new/mixed formats
+2. **Creates a backup** (unless `--no-backup` is specified)
+3. **For each old-structure node directory**:
+   - **If node has attributes file**: Moves `identifier/attributes.yml` → `identifier.yml` (at collection level)
+   - **If node has NO attributes**: Creates empty `identifier.yml` with `{}` content
+   - Assets remain in `identifier/assets/` (no change needed!)
+
+**Important**: The migrator processes ALL node directories, even those without an attributes file. This ensures every node is discoverable in the new structure.
+
+### Safety Features
+
+- **Automatic backups**: Creates timestamped backup before migration
+- **Dry run mode**: Preview changes before applying
+- **Validation**: Detects mixed structures and warns
+- **Rollback support**: Can restore from backup if needed
+
+## Manual Migration
+
+If you prefer to migrate manually:
+
+1. **For each node WITH attributes**:
+   ```bash
+   cd posts
+
+   # Move metadata file out to collection level
+   mv sample-post/attributes.yml sample-post.yml
+
+   # Assets stay in sample-post/assets/
+   ```
+
+2. **For each node WITHOUT attributes** (assets-only):
+   ```bash
+   cd posts
+
+   # Create empty metadata file at collection level
+   echo '{}' > orphan-assets.yml
+
+   # Assets stay in orphan-assets/assets/
+   ```
+
+3. **Update your code** to use Ro v5.0
+
+## Rollback
+
+If you need to rollback after migration:
+
+```ruby
+# Using the Migrator class
+migrator = Ro::Migrator.new('/path/to/ro/root')
+migrator.rollback
+```
+
+This will restore from the most recent backup.
+
+## Migration Checklist
+
+- [ ] Review migration plan with `--dry-run`
+- [ ] Backup your data (migration creates backup automatically)
+- [ ] Run migration: `./bin/ro migrate /path/to/ro/root`
+- [ ] Verify migrated data loads correctly
+- [ ] Test your application with new structure
+- [ ] Update code to Ro v5.0 if needed
+- [ ] Remove old backups once confident
+
+## Breaking Changes
+
+### API Changes
+
+**Node initialization**:
+```ruby
+# Old (v4.x) - still works for backward compatibility
+node = Ro::Node.new(node_directory_path)
+
+# New (v5.0) - preferred for new structure
+node = Ro::Node.new(collection, metadata_file)
+```
+
+**Asset paths**:
+```ruby
+# Both old and new structure
+node.asset_dir  # => identifier/assets/
+
+# The assets/ subdirectory stays the same!
+# Only the metadata file location changes
+```
+
+### What Stays the Same
+
+- **Metadata format**: YAML/JSON/TOML structure unchanged
+- **Asset access**: `node.assets`, `node.asset_paths` work the same
+- **Collection access**: `root['collection']['node']` unchanged
+- **Attribute access**: `node[:title]`, `node.attributes` unchanged
+
+## Testing
+
+Run tests to verify migration:
+
+```bash
+# Unit tests
+ruby test/unit/collection_test.rb
+ruby test/unit/node_test.rb
+ruby test/unit/asset_test.rb
+ruby test/unit/migrator_test.rb
+
+# Integration tests
+ruby test/integration/ro_integration_test.rb
+```
+
+## Troubleshooting
+
+### "Both old and new structures detected"
+
+This indicates a partial migration. Options:
+1. Use `--force` to continue migration
+2. Manually inspect and resolve conflicts
+3. Restore from backup and retry
+
+### "Node directory not found"
+
+Ensure you're running the migration from the correct root directory.
+
+### Assets not loading after migration
+
+Check that:
+1. Metadata files are at collection level (e.g., `posts/sample-post.yml`)
+2. Node directories exist at collection level (e.g., `posts/sample-post/`)
+3. Assets are in the `assets/` subdirectory (e.g., `posts/sample-post/assets/image.jpg`)
+
+## Examples
+
+### Example 1: Single Collection
+
+Before:
+```
+ro_data/
+  posts/
+    welcome/
+      attributes.yml
+      assets/
+        banner.jpg
+```
+
+After:
+```
+ro_data/
+  posts/
+    welcome.yml          ← Metadata moved out
+    welcome/
+      assets/
+        banner.jpg       ← Assets stay in same location
+```
+
+### Example 2: Multiple Collections
+
+Before:
+```
+ro_data/
+  posts/
+    post-1/
+      attributes.yml
+      assets/
+        image.jpg
+  pages/
+    about/
+      attributes.yml
+      assets/
+        photo.png
+```
+
+After:
+```
+ro_data/
+  posts/
+    post-1.yml
+    post-1/
+      assets/
+        image.jpg
+  pages/
+    about.yml
+    about/
+      assets/
+        photo.png
+```
+
+### Example 3: Metadata-Only Node
+
+Before:
+```
+ro_data/
+  posts/
+    text-only/
+      attributes.yml
+```
+
+After:
+```
+ro_data/
+  posts/
+    text-only.yml
+```
+
+### Example 4: Assets-Only Node (No Attributes)
+
+Before:
+```
+ro_data/
+  posts/
+    orphan-assets/     ← Directory with no attributes.yml
+      assets/
+        image.jpg
+```
+
+After:
+```
+ro_data/
+  posts/
+    orphan-assets.yml  ← Empty metadata file created: {}
+    orphan-assets/
+      assets/
+        image.jpg
+```
+
+## Support
+
+For issues or questions:
+- GitHub Issues: https://github.com/ahoward/ro/issues
+- Documentation: See README.md and code comments
+
+## Version Compatibility
+
+- **Ro v4.x**: Old structure only
+- **Ro v5.0**: Both structures (with backward compatibility)
+- **Ro v6.0+**: New structure only (planned)
+
+**Recommendation**: Migrate to new structure before Ro v6.0 release.

data/README.md

@@ -9,7 +9,7 @@ it is one part cms, one part database, one part api, and one part magic.
 
 if you used a headless cms, it's like that, before they existed, except way better, and free.
 
-with `ro`, you can seperate your content from presentation, like a sane and decent human being.
+with `ro`, you can separate your content from presentation, like a sane and decent human being.
 
 > silent code whispers
 > github's gentle, peaceful hush
@@ -36,16 +36,17 @@ for a real site.
 
 ```sh
 
-  drawohara@drawohara.dev:ro[main] #=> tree public/ro/posts/almost-died-in-an-ice-cave/
-  public/ro/posts/almost-died-in-an-ice-cave/
-  ├── assets
-  │   ├── image1.png
-  │   ├── image2.png
-  │   ├── image3.png
-  │   ├── og.jpg
-  │   └── purple-heart.jpg
-  ├── attributes.yml
-  └── body.md
+  drawohara@drawohara.dev:ro[main] #=> tree public/ro/posts/
+  public/ro/posts/
+  ├── almost-died-in-an-ice-cave.yml    # ← metadata file at collection level
+  └── almost-died-in-an-ice-cave/       # ← node directory
+      ├── assets/                        # ← assets subdirectory
+      │   ├── image1.png
+      │   ├── image2.png
+      │   ├── image3.png
+      │   ├── og.jpg
+      │   └── purple-heart.jpg
+      └── body.md                        # ← other content files
 
 ```
 
@@ -53,15 +54,22 @@ in this example you can see a few things, regarding the layout of a `ro` directo
 
 - `ro` content often, but is not required, to live in `public`.  more on this below.
 
-- the essential layout is
+- the essential layout is (v5.0+):
 
 ```ruby
 
     @root       = "ro"
     @collection = "posts"
-    @id          = "almost-died-in-an-ice-cave"
+    @id         = "almost-died-in-an-ice-cave"
 
-    "#{ @root }/#{ @collection }/#{ @id }"
+    # metadata file
+    "#{ @root }/#{ @collection }/#{ @id }.yml"
+
+    # node directory
+    "#{ @root }/#{ @collection }/#{ @id }/"
+
+    # assets
+    "#{ @root }/#{ @collection }/#{ @id }/assets/"
 
 ```
 
@@ -85,7 +93,7 @@ if you learn best by example, you can examine the `ro` directory of my own websi
 
 more about this can be rtfm'd here -> https://github.com/ahoward/ro/blob/main/lib/ro.rb#L29-L55
 
-because not having a repl sucks, so `ro` has one.  you should too.
+because not having a repl sucks, `ro` has one.  you should too.
 
 ```sh
 
@@ -158,7 +166,7 @@ you will end up with html that looks like so:
 
 <a href='/ro/posts/foo-bar/assets/report.pdf'>linky</a>
 
-<img src='/ro/posts/foo-bar/assets/pretty.png'>alty</a>
+<img src='/ro/posts/foo-bar/assets/pretty.png' alt='alty'>
 
 
 ```
@@ -195,13 +203,13 @@ attributes will be expanded too, at any depth.  eg. -> https://github.com/ahowar
 this means code like this:
 
 ```yaml
-# file: public/ro/posts/foo-bar/attributes.yml
+# file: public/ro/posts/foo-bar.yml
 
 og:
   image: ./assets/og.jpg
 ```
 
-will 'just work'. of course, this assumes that 'public/ro/foo-bar/assets/og.jpg' exists!
+will 'just work'. of course, this assumes that 'public/ro/posts/foo-bar/assets/og.jpg' exists!
 
 the code is rather robust here, and is not a simple string bashing approach.
 
@@ -266,7 +274,7 @@ lil detail about that link^, it is from *10 years ago*, when dojo4 was still run
 
 ---
 
-one super comman pattern, is to add a build step to a github workflow, and
+one super common pattern, is to add a build step to a github workflow, and
 then publish the js api via gh-pages. see an example here:
 
 https://github.com/ahoward/ro/blob/main/.github/workflows/gh-pages.yml
@@ -339,3 +347,7 @@ https://github.com/LGUG2Z/komorebi-license
 AI
 --
 suck it 🤖s!
+
+REF
+---
+https://github.com/ahoward/ro

data/a.yml

@@ -0,0 +1,60 @@
+# Simple workflow for deploying static content to GitHub Pages
+name: deploy ro content, api, and site to gh-pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # single deploy job since we're just deploying
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: checkout
+        # NOTE: this enables git-lfs and caching
+        # - https://github.com/actions/checkout/issues/834
+        # - https://github.com/nschloe/action-cached-lfs-checkout
+        uses: nschloe/action-cached-lfs-checkout@v1
+        # you may use this instead, if you don't want git-lfs caching
+        #uses: actions/checkout@v4
+        #with:
+        #   lfs: true
+      - name: setup gh-pages
+        uses: actions/configure-pages@v3
+        id: gh-pages
+      - name: ro build
+        uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+      - run: |
+            export RO_URL=${{ steps.gh-pages.outputs.base_url }}/ro
+            export RO_PAGE_SIZE=2
+            bundle exec ./bin/ro build ./public/ro ./public/api/ro
+            bundle exec ro site public
+            tree ./public
+      - name: upload artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: "./public"
+      - name: deploy gh-pages
+        id: deployment
+        uses: actions/deploy-pages@v2

data/bin/ro

@@ -130,6 +130,10 @@ Ro.script do
     site!
   end
 
+  run(:migrate) do
+    migrate!
+  end
+
   def setup!(*which)
     setup_env!
 
@@ -259,6 +263,12 @@ Ro.script do
     index_html.binwrite(html)
     puts index_html
   end
+
+  def migrate!
+    require "#{$libdir}/ro/script/migrate.rb"
+
+    Ro::Script::Migrate.run!(script: self)
+  end
 end
 
 BEGIN {

data/lib/ro/_lib.rb

@@ -1,5 +1,5 @@
 module Ro
-  VERSION = '4.4.0' unless defined?(VERSION)
+  VERSION = '5.1.0' unless defined?(VERSION)
 
   class << self
     def version

data/lib/ro/asset.rb

@@ -9,13 +9,53 @@ module Ro
 
       @path = Path.for(arg, *args)
 
-      @node = options.fetch(:node) { Node.for(@path.split('/assets/').first) }
-
-      @relative_path = @path.relative_to(@node.path)
+      # T029: Updated to split on node ID instead of /assets/ segment
+      @node = options.fetch(:node) do
+        # Try to find node by splitting path
+        # In new structure: no /assets/ segment
+        # In old structure: /assets/ segment exists
+        if @path.to_s.include?('/assets/')
+          # Old structure
+          Node.for(@path.split('/assets/').first)
+        else
+          # New structure: find node directory by looking at parent paths
+          # Asset path like: /collection/node-id/file.jpg
+          # Node path should be: /collection/node-id
+          found_node = nil
+          node_path = @path.parent
+          while node_path && !node_path.basename.to_s.match(/\.(yml|yaml|json|toml)$/)
+            # Check if there's a metadata file for this directory
+            collection_path = node_path.parent
+            node_id = node_path.basename.to_s
+
+            %w[yml yaml json toml].each do |ext|
+              metadata_file = collection_path.join("#{node_id}.#{ext}")
+              if metadata_file.exist?
+                root = Root.for(collection_path.parent)
+                collection = root.collection_for(collection_path)
+                found_node = Node.new(collection, metadata_file)
+                break
+              end
+            end
+
+            break if found_node
+            node_path = node_path.parent
+          end
+
+          # Fallback: old behavior
+          found_node || Node.for(@path.split('/assets/').first)
+        end
+      end
+
+      # T030: Updated relative_path calculation for new structure
+      # In new structure, path is already relative to node.asset_dir
+      # In old structure, need to account for assets/ prefix
+      @relative_path = @path.relative_to(@node.asset_dir)
 
       @name = @relative_path
 
-      @url = @node.url_for(@relative_path)
+      # URL needs to include 'assets/' prefix since assets live in assets/ subdirectory
+      @url = @node.url_for(Path.relative('assets', @relative_path))
 
       super(@path)
     end
@@ -33,8 +73,10 @@ module Ro
 
     def is_src?
       key = relative_path.parts
-      subdir = key.size > 2 ? key[1] : nil
-      !!(subdir == 'src')
+      # Check if the first directory in the path is 'src'
+      # e.g., src/file.js or src/subdir/file.js
+      first_dir = key.size >= 2 ? key[0] : nil
+      !!(first_dir == 'src')
     end
 
     alias is_src is_src?