mechanomeld 0.1.1-x86_64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 664132a1c219f2a6bb45b5ee806e021728ff9e44c0638bc34ec697c195eeccf3
+  data.tar.gz: a366cce5bf9f2dbe5d5a66bfd3348ac7920af5a89638cd32213ad87a356b7dbd
+SHA512:
+  metadata.gz: 381b73f53f663f69dd40a7e339e43d308456d18a056c6487fd0f192b6ee3c3b9e2170c9b2ef86701e1a01a23a60ba98af02b6242688019758bf2dccbf34a83b3
+  data.tar.gz: 63584e963a9845ac188a51fae3bd4fe8ba4ff275ac1cd2726c3ca914833741f7cc4369b1f19813a049eafff5d765cbc9b4f2226af56acc41cb4d49c0b7c53331

data/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/)
+and this project adheres to [Semantic Versioning](http://semver.org/).
+
+## [0.1.1] - 2026-09-25
+
+### Added
+
+- Document#load_incremental applies saved Automerge bytes into an existing document (d60a3eb)
+- Document.load_repo reads a document from automerge-repo's NodeFSStorageAdapter directory (d60a3eb)
+- Document#heads returns the document's change hashes as hex, matching JavaScript's Automerge.getHeads (d60a3eb)
+- Document#includes_heads?(heads) reports whether a document is at or past a set of heads (d60a3eb)
+- Mechanomeld::SyncState, the per-peer sync state, with encode and decode for persistence (eea3a51)
+- Document#generate_sync_message and #receive_sync_message, Automerge's per-document sync protocol (eea3a51)
+
+### Changed
+
+- releases also publish an x86_64-linux-musl platform gem (159dd59)
+
+## [0.1.0] - 2026-09-17
+
+### Added
+
+- Initial release
+- Mechanomeld::Counter, Timestamp, Uint, Bytes, and Text value classes (6df6951)
+- Mechanomeld::Document.load reads documents saved by JavaScript Automerge (c7d31d8)
+- Document#get, #[], and #to_h read values by path (c7d31d8)
+- Document#keys and #length for maps, lists, and text (1d80c0b)
+- Mechanomeld::Document.new(actor_id:) creates an empty document (bccb69c)
+- Document#put, #[]=, #delete, and #save (bccb69c)
+- Document#commit(message:, timestamp:) and #rollback (a8ef491)
+- Document#change commits a block and rolls back if it raises (a8ef491)
+- Mechanomeld::Document.from builds a committed document from a Hash (a8ef491)

data/README.md

@@ -0,0 +1,115 @@
+# Mechanomeld
+
+Read and write [Automerge](https://automerge.org) documents from Ruby. Mechanomeld is a native extension around the Rust `automerge` crate, so documents round-trip with JavaScript's `@automerge/automerge`.
+
+## Installation
+
+```bash
+bundle add mechanomeld
+```
+
+Precompiled gems are published for arm64/x86_64 macOS and Linux on Ruby 3.2–4.0. Other platforms build from source and need a Rust toolchain.
+
+## Usage
+
+```ruby
+require "mechanomeld"
+
+doc = Mechanomeld::Document.load(File.binread("todos.automerge"))
+doc.get(["todos", 0, "title"]) # => #<Mechanomeld::Text "Buy milk">
+doc.to_h                       # => {"todos" => [{"title" => #<Mechanomeld::Text "Buy milk">, ...}]}
+doc.keys                       # => ["todos"]
+doc.length("todos")            # => 1
+
+doc = Mechanomeld::Document.from({"title" => Mechanomeld::Text.new("Groceries"), "items" => []})
+doc.change(message: "Add milk") do |d|
+  d["count"] = Mechanomeld::Counter.new(1)
+end
+File.binwrite("groceries.automerge", doc.save)
+```
+
+### Documents stored by automerge-repo
+
+`Document.load_repo` reads a document straight out of the directory written by `@automerge/automerge-repo`'s `NodeFSStorageAdapter`, applying its snapshot and incremental chunks and skipping its sync-state files.
+
+```ruby
+doc = Mechanomeld::Document.load_repo("automerge-repo-data", "4NtRZtd6yUtzf8qmEpKitAaW4JRp")
+```
+
+`Document#load_incremental(bytes)` is the piece underneath: it applies any saved Automerge bytes (a full save, a snapshot chunk, or an incremental change chunk) into an existing document and returns the document.
+
+### Heads
+
+`Document#heads` is the document's version: the change hashes JavaScript's `Automerge.getHeads(doc)` returns, as lowercase hex, so the two sides compare with `==`. `Document#includes_heads?(heads)` is true when every hash in `heads` is a change the document already contains, so `heads` is the same version or an older one.
+
+```ruby
+doc.heads                  # => ["9d434616e7af865757bad75cdebe4151bccf7e29214a71f2a65150846c2a4275"]
+doc.includes_heads?(heads) # => true when the document is at or past `heads`
+```
+
+Both take hex. automerge-repo's `handle.heads()` returns base58 URL heads, which are not accepted; send `Automerge.getHeads(handle.doc())` from JavaScript instead. A hash that is not 32 bytes of hex raises `Mechanomeld::Error`; a well-formed hash the document does not have is simply not included. Like `save`, both commit any pending change first.
+
+### Syncing with a peer
+
+`Document#generate_sync_message` and `Document#receive_sync_message` run Automerge's per-document sync protocol, so a Ruby document can exchange just the changes each side lacks with another Automerge peer: JavaScript's `Automerge.generateSyncMessage` / `receiveSyncMessage`, or another Ruby document. A `Mechanomeld::SyncState` tracks what one peer is known to have; keep one per peer for each document.
+
+```ruby
+left = Mechanomeld::Document.load(bytes)
+right = Mechanomeld::Document.load(bytes)
+left.change { |d| d["left"] = 1 }
+right.change { |d| d["right"] = 2 }
+
+left_state = Mechanomeld::SyncState.new  # left's view of right
+right_state = Mechanomeld::SyncState.new # right's view of left
+loop do
+  to_right = left.generate_sync_message(left_state)
+  right.receive_sync_message(right_state, to_right) if to_right
+  to_left = right.generate_sync_message(right_state)
+  left.receive_sync_message(left_state, to_left) if to_left
+  break if to_right.nil? && to_left.nil?
+end
+left.heads == right.heads # => true
+```
+
+Messages are binary Strings. `generate_sync_message` returns nil when the peer is up to date or the last message is still unanswered. `SyncState#encode` and `SyncState.decode(bytes)` carry a state across connections, keeping only the heads both sides are known to share (as JavaScript's `encodeSyncState` does), so a process that handles one message per request can decode, receive, generate, and encode again. Like `save`, both sync methods commit any pending change first. Bytes that are not a sync message or a sync state raise `Mechanomeld::Error`. The protocol carries no document identity: a message from a peer holding a different document merges that document in.
+
+This is the per-document protocol only. An automerge-repo sync server wraps these messages in its own envelope (peer and document ids, join and leave messages, CBOR encoding), which this gem does not provide.
+
+### Values
+
+| Automerge | Ruby |
+|---|---|
+| map / list | `Hash` (String keys) / `Array` |
+| text object | `Mechanomeld::Text` |
+| string | `String` |
+| int / f64 / boolean / null | `Integer` / `Float` / `true`, `false` / `nil` |
+| counter / uint | `Mechanomeld::Counter` / `Mechanomeld::Uint` |
+| timestamp | `Mechanomeld::Timestamp` (milliseconds since the epoch) |
+| bytes | `Mechanomeld::Bytes` |
+
+JavaScript stores strings as text objects by default, so they read as `Mechanomeld::Text`. A Ruby `String` is written as an Automerge string, which JavaScript reads as an `ImmutableString`; write `Mechanomeld::Text.new("...")` to create text JavaScript reads as a plain string.
+
+Errors from Automerge raise `Mechanomeld::Error`.
+
+## Development
+
+Tools are pinned in `mise.toml`.
+
+```bash
+mise trust
+mise install
+mise run setup         # bundle install, npm ci for fixtures
+mise run test          # compile the extension and run the tests
+mise run test:interop  # check JavaScript reads Ruby-written documents
+mise run fixtures      # regenerate test/fixtures/*.automerge, heads.json, and repo/
+```
+
+Check packaging with `gem build mechanomeld.gemspec`. Do not run `rake build` or `rake release` locally: reissue bumps the version and commits during `build`.
+
+## Releasing
+
+Releases run from the **Release gem to RubyGems.org** GitHub Actions workflow. Changelog entries and version bumps come from commit trailers (`Added:`, `Changed:`, `Fixed:`, `Version: minor`, ...). Run it with `dry_run` first.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/SOFware/mechanomeld.

data/Rakefile

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+require "rb_sys/extensiontask"
+require "reissue/gem"
+
+GEMSPEC = Gem::Specification.load("mechanomeld.gemspec")
+
+# No platform list: cross-gem builds set RUBY_TARGET, which rb_sys reads.
+RbSys::ExtensionTask.new("mechanomeld", GEMSPEC) do |ext|
+  ext.lib_dir = "lib/mechanomeld"
+end
+
+Minitest::TestTask.create
+task test: :compile
+
+Reissue::Task.create :reissue do |task|
+  task.version_file = "lib/mechanomeld/version.rb"
+  task.fragment = :git
+  # The post-release bump goes on a pushed branch; the shared release workflow opens its PR.
+  # (0.5.1's default, stated explicitly: it is the "Option A" the shared workflow expects.)
+  task.push_reissue = :branch
+end
+
+task default: :test

data/checksums/mechanomeld-0.1.0.gem.sha512

@@ -0,0 +1 @@
+4a15ef106109b7d61c0c5f78cfc6f1599300b62a5410dbeb7e673cecd69731907125e006507dfc2b03eea8d6a738031569e5f430adcc0cb051fd36d7bdfcee4e

data/lib/mechanomeld/document.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Mechanomeld
+  # Native methods (new, load, load_incremental, get, keys, length, put, delete, commit,
+  # rollback, save, heads, includes_heads?, generate_sync_message, receive_sync_message)
+  # are defined in ext/mechanomeld/src/document.rs.
+  class Document
+    def self.from(hash, actor_id: nil)
+      raise ArgumentError, "Automerge document root must be a Hash" unless hash.is_a?(Hash)
+
+      doc = new(actor_id: actor_id)
+      hash.each { |key, value| doc.put([key], value) }
+      doc.commit
+      doc
+    end
+
+    # Loads a document from the directory written by @automerge/automerge-repo's
+    # NodeFSStorageAdapter. Snapshot chunks are applied before incremental ones, as
+    # automerge-repo does; its sync-state files are not document data and are skipped.
+    def self.load_repo(base_dir, document_id)
+      document_dir = File.join(base_dir, document_id[0, 2], document_id[2..])
+      chunks = %w[snapshot incremental].flat_map do |kind|
+        Dir.glob(File.join(document_dir, kind, "*")).sort.select { |path| File.file?(path) }
+      end
+      raise Error, "no chunks for document #{document_id} in #{base_dir}" if chunks.empty?
+
+      chunks.each_with_object(new) { |path, doc| doc.load_incremental(File.binread(path)) }
+    end
+
+    def [](path)
+      get(path)
+    end
+
+    def []=(path, value)
+      put(path, value)
+    end
+
+    def to_h
+      get([])
+    end
+    alias_method :to_hash, :to_h
+
+    def change(message: nil, timestamp: nil)
+      yield self
+      commit(message: message, timestamp: timestamp)
+      self
+    rescue Exception
+      rollback
+      raise
+    end
+  end
+end

data/lib/mechanomeld/error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Mechanomeld
+  class Error < StandardError; end
+end

data/lib/mechanomeld/scalars.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Mechanomeld
+  # A typed Automerge value that has no natural Ruby equivalent.
+  class Scalar
+    attr_reader :value
+
+    def initialize(value)
+      @value = value
+    end
+
+    def ==(other)
+      other.class == self.class && other.value == value
+    end
+    alias_method :eql?, :==
+
+    def hash
+      [self.class, value].hash
+    end
+
+    def inspect
+      "#<#{self.class.name} #{value.inspect}>"
+    end
+  end
+
+  class Counter < Scalar; end
+
+  # Milliseconds since the Unix epoch.
+  class Timestamp < Scalar; end
+
+  class Uint < Scalar; end
+
+  class Bytes < Scalar
+    def initialize(value)
+      super(String(value).b)
+    end
+  end
+
+  # A collaborative text object, as opposed to a plain String value.
+  class Text < Scalar
+    def initialize(value = "")
+      super(String(value))
+    end
+
+    def to_s
+      value
+    end
+  end
+end

data/lib/mechanomeld/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Mechanomeld
+  VERSION = "0.1.1"
+end

data/lib/mechanomeld.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "mechanomeld/version"
+require_relative "mechanomeld/error"
+require_relative "mechanomeld/scalars"
+
+# Precompiled gems ship one binary per Ruby minor version; source builds put it in lib/mechanomeld.
+begin
+  RUBY_VERSION =~ /(\d+\.\d+)/
+  require_relative "mechanomeld/#{Regexp.last_match(1)}/mechanomeld"
+rescue LoadError
+  require_relative "mechanomeld/mechanomeld"
+end
+
+require_relative "mechanomeld/document"

data/sig/mechanomeld.rbs

@@ -0,0 +1,4 @@
+module Mechanomeld
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: mechanomeld
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: x86_64-linux
+authors:
+- Jim Gay
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2026-09-25 00:00:00.000000000 Z
+dependencies: []
+description: A native extension wrapping the Rust automerge crate so Ruby can load,
+  read, create, and save Automerge documents shared with JavaScript.
+email:
+- jim@saturnflyer.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- Rakefile
+- checksums/mechanomeld-0.1.0.gem.sha512
+- lib/mechanomeld.rb
+- lib/mechanomeld/3.2/mechanomeld.so
+- lib/mechanomeld/3.3/mechanomeld.so
+- lib/mechanomeld/3.4/mechanomeld.so
+- lib/mechanomeld/4.0/mechanomeld.so
+- lib/mechanomeld/document.rb
+- lib/mechanomeld/error.rb
+- lib/mechanomeld/scalars.rb
+- lib/mechanomeld/version.rb
+- sig/mechanomeld.rbs
+homepage: https://github.com/SOFware/mechanomeld
+licenses: []
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/SOFware/mechanomeld
+  source_code_uri: https://github.com/SOFware/mechanomeld
+  changelog_uri: https://github.com/SOFware/mechanomeld/blob/main/CHANGELOG.md
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 4.1.dev
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.23
+signing_key: 
+specification_version: 4
+summary: Read and write Automerge documents from Ruby
+test_files: []