fosm-rails 0.1.0

data/lib/fosm/lifecycle/state_definition.rb

@@ -0,0 +1,18 @@
+module Fosm
+  module Lifecycle
+    class StateDefinition
+      attr_reader :name
+
+      def initialize(name:, initial: false, terminal: false)
+        @name = name.to_sym
+        @initial = initial
+        @terminal = terminal
+      end
+
+      def initial? = @initial
+      def terminal? = @terminal
+
+      def to_s = @name.to_s
+    end
+  end
+end

data/lib/fosm/lifecycle.rb

@@ -0,0 +1,173 @@
+require_relative "lifecycle/definition"
+
+module Fosm
+  module Lifecycle
+    extend ActiveSupport::Concern
+
+    included do
+      # The lifecycle definition is stored as a class attribute
+      class_attribute :fosm_lifecycle, instance_accessor: false
+
+      # Validations
+      before_validation :fosm_set_initial_state, on: :create
+      validates :state, inclusion: { in: ->(record) { record.class.fosm_lifecycle&.state_names || [] } },
+                        allow_blank: false,
+                        if: -> { self.class.fosm_lifecycle.present? }
+    end
+
+    class_methods do
+      # The lifecycle DSL entry point
+      def lifecycle(&block)
+        self.fosm_lifecycle = Fosm::Lifecycle::Definition.new
+        self.fosm_lifecycle.instance_eval(&block)
+
+        # Generate state predicate methods: invoice.draft? => true
+        fosm_lifecycle.states.each do |state_def|
+          define_method(:"#{state_def.name}?") do
+            self.state.to_s == state_def.name.to_s
+          end
+        end
+
+        # Generate dynamic bang methods per event: invoice.send_invoice!(actor: user)
+        fosm_lifecycle.events.each do |event_def|
+          define_method(:"#{event_def.name}!") do |actor: nil, metadata: {}|
+            fire!(event_def.name, actor: actor, metadata: metadata)
+          end
+
+          define_method(:"can_#{event_def.name}?") do
+            can_fire?(event_def.name)
+          end
+        end
+      end
+    end
+
+    # Fire a lifecycle event. This is the ONLY way to change state.
+    #
+    # @param event_name [Symbol, String] the event to fire
+    # @param actor [Object] who/what is firing the event (User, or symbol like :system, :agent)
+    # @param metadata [Hash] optional metadata stored in the transition log
+    # @raise [Fosm::UnknownEvent] if event doesn't exist
+    # @raise [Fosm::TerminalState] if current state is terminal
+    # @raise [Fosm::InvalidTransition] if current state doesn't allow this event
+    # @raise [Fosm::GuardFailed] if a guard blocks the transition
+    def fire!(event_name, actor: nil, metadata: {})
+      lifecycle = self.class.fosm_lifecycle
+      raise Fosm::Error, "No lifecycle defined on #{self.class.name}" unless lifecycle
+
+      event_def = lifecycle.find_event(event_name)
+      raise Fosm::UnknownEvent.new(event_name, self.class) unless event_def
+
+      current = self.state.to_s
+      current_state_def = lifecycle.find_state(current)
+
+      # Block terminal states from further transitions
+      if current_state_def&.terminal?
+        raise Fosm::TerminalState.new(current, self.class)
+      end
+
+      # Check the transition is valid from current state
+      unless event_def.valid_from?(current)
+        raise Fosm::InvalidTransition.new(event_name, current, self.class)
+      end
+
+      # Run guards
+      event_def.guards.each do |guard_def|
+        unless guard_def.call(self)
+          raise Fosm::GuardFailed.new(guard_def.name, event_name)
+        end
+      end
+
+      from_state = current
+      to_state = event_def.to_state.to_s
+
+      transition_data = { from: from_state, to: to_state, event: event_name.to_s, actor: actor }
+
+      ActiveRecord::Base.transaction do
+        update!(state: to_state)
+
+        # Write immutable transition log
+        Fosm::TransitionLog.create!(
+          record_type: self.class.name,
+          record_id: self.id.to_s,
+          event_name: event_name.to_s,
+          from_state: from_state,
+          to_state: to_state,
+          actor_type: actor_type_for(actor),
+          actor_id: actor_id_for(actor),
+          actor_label: actor_label_for(actor),
+          metadata: metadata
+        )
+
+        # Run side effects inside transaction so they can roll back on error
+        event_def.side_effects.each do |side_effect_def|
+          side_effect_def.call(self, transition_data)
+        end
+      end
+
+      # Deliver webhooks asynchronously (outside transaction)
+      Fosm::WebhookDeliveryJob.perform_later(
+        record_type: self.class.name,
+        record_id: self.id.to_s,
+        event_name: event_name.to_s,
+        from_state: from_state,
+        to_state: to_state,
+        metadata: metadata
+      )
+
+      true
+    end
+
+    # Returns true if the given event can be fired from the current state
+    def can_fire?(event_name)
+      lifecycle = self.class.fosm_lifecycle
+      return false unless lifecycle
+
+      event_def = lifecycle.find_event(event_name)
+      return false unless event_def
+      return false if lifecycle.find_state(self.state)&.terminal?
+      return false unless event_def.valid_from?(self.state)
+
+      event_def.guards.all? { |guard_def| guard_def.call(self) }
+    end
+
+    # Returns list of event names that can be fired from the current state
+    def available_events
+      lifecycle = self.class.fosm_lifecycle
+      return [] unless lifecycle
+
+      lifecycle.available_events_from(self.state).select { |event_def|
+        event_def.guards.all? { |g| g.call(self) }
+      }.map(&:name)
+    end
+
+    # Returns the current state as a symbol
+    def current_state
+      self.state.to_sym
+    end
+
+    private
+
+    def fosm_set_initial_state
+      return if self.state.present?
+      initial = self.class.fosm_lifecycle&.initial_state
+      self.state = initial.name.to_s if initial
+    end
+
+    def actor_type_for(actor)
+      return nil if actor.nil?
+      return "symbol" if actor.is_a?(Symbol)
+      actor.class.name
+    end
+
+    def actor_id_for(actor)
+      return nil if actor.nil? || actor.is_a?(Symbol)
+      actor.respond_to?(:id) ? actor.id.to_s : nil
+    end
+
+    def actor_label_for(actor)
+      return actor.to_s if actor.is_a?(Symbol)
+      return nil unless actor
+      actor.respond_to?(:email) ? actor.email : actor.to_s
+    end
+  end
+end

data/lib/fosm/rails/engine.rb

@@ -0,0 +1,9 @@
+# Legacy shim — the real engine is Fosm::Engine defined in lib/fosm/engine.rb
+require_relative "../engine"
+
+module Fosm
+  module Rails
+    # Kept for backward compatibility. Aliases the real engine.
+    Engine = Fosm::Engine
+  end
+end

data/lib/fosm/rails/version.rb

@@ -0,0 +1,9 @@
+require_relative "../version"
+
+module Fosm
+  module Rails
+    # Legacy constant kept for backward compatibility.
+    # The primary version is Fosm::VERSION.
+    VERSION = Fosm::VERSION
+  end
+end

data/lib/fosm/rails.rb

@@ -0,0 +1,9 @@
+# Legacy entry point — kept for backward compatibility.
+# The primary entry point is lib/fosm-rails.rb.
+require "fosm-rails"
+
+module Fosm
+  module Rails
+    # Shim module so any code that references Fosm::Rails still loads cleanly.
+  end
+end

data/lib/fosm/registry.rb

@@ -0,0 +1,29 @@
+module Fosm
+  # Global registry of all FOSM app model classes.
+  # Models auto-register when they include Fosm::Lifecycle and call lifecycle { }.
+  module Registry
+    @registered = {}
+
+    class << self
+      def register(model_class, slug:)
+        @registered[slug] = model_class
+      end
+
+      def all
+        @registered
+      end
+
+      def find(slug)
+        @registered[slug]
+      end
+
+      def model_classes
+        @registered.values
+      end
+
+      def slugs
+        @registered.keys
+      end
+    end
+  end
+end

data/lib/fosm/version.rb

@@ -0,0 +1,3 @@
+module Fosm
+  VERSION = "0.1.0"
+end

data/lib/fosm-rails.rb

@@ -0,0 +1,40 @@
+require "gemlings"
+require "fosm/version"
+require "fosm/errors"
+require "fosm/configuration"
+require "fosm/registry"
+require "fosm/lifecycle"
+require "fosm/agent"
+require "fosm/engine"
+
+module Fosm
+  # FOSM — Finite Object State Machine for Rails
+  #
+  # Include Fosm::Lifecycle in any ActiveRecord model to give it a
+  # formal, enforced lifecycle with states, events, guards, and side-effects.
+  #
+  # Quick start:
+  #
+  #   class Invoice < ApplicationRecord
+  #     include Fosm::Lifecycle
+  #
+  #     lifecycle do
+  #       state :draft,     initial: true
+  #       state :sent
+  #       state :paid,      terminal: true
+  #       state :cancelled, terminal: true
+  #
+  #       event :send_invoice, from: :draft, to: :sent
+  #       event :pay,          from: :sent,  to: :paid
+  #       event :cancel,       from: [:draft, :sent], to: :cancelled
+  #
+  #       guard :has_line_items, on: :send_invoice do |invoice|
+  #         invoice.amount > 0
+  #       end
+  #
+  #       side_effect :notify_client, on: :send_invoice do |invoice, transition|
+  #         InvoiceMailer.send_to_client(invoice).deliver_later
+  #       end
+  #     end
+  #   end
+end

data/lib/generators/fosm/app/app_generator.rb

@@ -0,0 +1,106 @@
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Fosm
+  module Generators
+    class AppGenerator < ::Rails::Generators::NamedBase
+      include ::Rails::Generators::Migration
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :fields, type: :array, default: [], banner: "field:type field:type",
+                             desc: "List of fields for the FOSM record table"
+      class_option :states, type: :string, default: "draft,active,completed",
+                             desc: "Comma-separated list of states (first is initial)"
+      class_option :access, type: :string, default: "",
+                             desc: "Authorization method (e.g. authenticate_user!, require_facilitator!)"
+
+      def self.next_migration_number(dirname)
+        ::ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      def create_model_file
+        template "model.rb.tt", "app/models/fosm/#{file_name}.rb"
+      end
+
+      def create_controller_file
+        template "controller.rb.tt", "app/controllers/fosm/#{file_name}_controller.rb"
+      end
+
+      def create_agent_file
+        template "agent.rb.tt", "app/agents/fosm/#{file_name}_agent.rb"
+      end
+
+      def create_view_files
+        template "views/index.html.erb.tt", "app/views/fosm/#{file_name}/index.html.erb"
+        template "views/show.html.erb.tt",  "app/views/fosm/#{file_name}/show.html.erb"
+        template "views/new.html.erb.tt",   "app/views/fosm/#{file_name}/new.html.erb"
+        template "views/_form.html.erb.tt", "app/views/fosm/#{file_name}/_form.html.erb"
+      end
+
+      def create_migration_file
+        migration_template "migration.rb.tt", "db/migrate/create_fosm_#{table_name}.rb"
+      end
+
+      def update_routes
+        routes_file = ::Rails.root.join("config/routes/fosm.rb")
+
+        route_entry = <<~RUBY
+          scope module: "fosm", path: "/fosm/apps", as: :fosm do
+            resources :#{plural_name}, controller: "#{file_name}" do
+              member { post :fire_event }
+            end
+          end
+        RUBY
+
+        if File.exist?(routes_file)
+          append_to_file routes_file, "\n#{route_entry}"
+        else
+          create_file routes_file, route_entry
+          # Also ensure main routes.rb draws from fosm.rb
+          main_routes = ::Rails.root.join("config/routes.rb")
+          unless File.read(main_routes).include?("draw :fosm")
+            inject_into_file main_routes, "\n  draw :fosm", after: "Rails.application.routes.draw do"
+          end
+        end
+      end
+
+      private
+
+      def states_list
+        options[:states].split(",").map(&:strip)
+      end
+
+      def initial_state
+        states_list.first
+      end
+
+      def table_name
+        file_name.pluralize
+      end
+
+      def plural_name
+        name.underscore.pluralize
+      end
+
+      def access_method
+        # Strip shell-escaped ! (zsh escapes ! in double-quoted strings as \!)
+        options[:access].gsub("\\!", "!")
+      end
+
+      def fields_for_migration
+        # Handle both styles:
+        #   --fields name:string amount:decimal   (array, multiple args)
+        #   --fields "name:string amount:decimal" (single quoted string)
+        raw_fields = options[:fields].join(" ").split(/[\s,]+/).reject(&:blank?)
+        raw_fields.map do |field|
+          parts = field.split(":")
+          { name: parts[0].strip, type: (parts[1] || "string").strip }
+        end
+      end
+
+      def fields_for_permit
+        fields_for_migration.map { |f| f[:name].to_sym }.inspect
+      end
+    end
+  end
+end

data/lib/generators/fosm/app/templates/agent.rb.tt

@@ -0,0 +1,26 @@
+module Fosm
+  # AI Agent for <%= class_name %> powered by Gemlings.
+  #
+  # Standard tools are auto-generated from the lifecycle definition:
+  #   - list_<%= plural_name %>           List records, optionally filtered by state
+  #   - get_<%= file_name %>              Get a specific record by ID
+  #   - get_available_events_for_<%= file_name %>  What events can fire from current state
+  #   - get_transition_history_for_<%= file_name %> Full audit trail for a record
+  #   - [event_name]_<%= file_name %>    One tool per lifecycle event (bounded!)
+  #
+  # The AI agent CANNOT bypass the state machine. If a transition isn't valid
+  # from the current state, the tool returns { success: false, error: ... }.
+  #
+  # Add custom tools below using fosm_tool:
+  class <%= class_name %>Agent < Fosm::Agent
+    model_class Fosm::<%= class_name %>
+
+    # Example custom tool:
+    # fosm_tool :find_<%= plural_name %>_needing_attention,
+    #           description: "Find <%= plural_name %> that need human review" do
+    #   Fosm::<%= class_name %>.where(state: "<%= states_list[0] %>")
+    #                          .where("created_at < ?", 48.hours.ago)
+    #                          .map { |r| { id: r.id, state: r.state } }
+    # end
+  end
+end

data/lib/generators/fosm/app/templates/controller.rb.tt

@@ -0,0 +1,56 @@
+module Fosm
+  class <%= class_name %>Controller < Fosm::ApplicationController
+    use_host_routes!
+    layout -> { Fosm.config.app_layout }
+<% if access_method.present? %>
+    before_action :<%= access_method %>
+<% end %>
+    before_action :set_record, only: [:show, :destroy]
+
+    def index
+      @records = Fosm::<%= class_name %>.order(created_at: :desc)
+    end
+
+    def show
+    end
+
+    def new
+      @record = Fosm::<%= class_name %>.new
+    end
+
+    def create
+      @record = Fosm::<%= class_name %>.new(record_params)
+      @record.created_by_id = fosm_current_user&.id
+      if @record.save
+        redirect_to fosm_<%= file_name %>_path(@record), notice: "<%= class_name.humanize %> created."
+      else
+        render :new, status: :unprocessable_entity
+      end
+    end
+
+    def fire_event
+      @record = Fosm::<%= class_name %>.find(params[:id])
+      event = params[:event]&.to_sym
+      @record.fire!(event, actor: fosm_current_user)
+      redirect_to fosm_<%= file_name %>_path(@record), notice: "Event '#{event}' fired successfully."
+    rescue Fosm::Error => e
+      redirect_to fosm_<%= file_name %>_path(@record), alert: e.message
+    end
+
+    def destroy
+      @record = Fosm::<%= class_name %>.find(params[:id])
+      @record.destroy
+      redirect_to fosm_<%= plural_name %>_path, notice: "<%= class_name.humanize %> deleted."
+    end
+
+    private
+
+    def set_record
+      @record = Fosm::<%= class_name %>.find(params[:id])
+    end
+
+    def record_params
+      params.require(Fosm::<%= class_name %>.model_name.param_key).permit(<%= fields_for_permit %>)
+    end
+  end
+end

data/lib/generators/fosm/app/templates/migration.rb.tt

@@ -0,0 +1,14 @@
+class CreateFosm<%= class_name.pluralize %> < ActiveRecord::Migration[8.1]
+  def change
+    create_table :fosm_<%= table_name %> do |t|
+      t.string :state, null: false, default: "<%= initial_state %>"
+      t.bigint :created_by_id, null: true  # FK to users — add if you have a users table
+<% fields_for_migration.each do |field| %>
+      t.<%= field[:type] %> :<%= field[:name] %>
+<% end %>
+      t.timestamps
+    end
+
+    add_index :fosm_<%= table_name %>, :state
+  end
+end

data/lib/generators/fosm/app/templates/model.rb.tt

@@ -0,0 +1,31 @@
+module Fosm
+  class <%= class_name %> < ApplicationRecord
+    include Fosm::Lifecycle
+
+    self.table_name = "fosm_<%= table_name %>"
+
+    # Uncomment if your app has a User model:
+    # belongs_to :created_by, class_name: "User", optional: true
+
+    lifecycle do
+      # States — first state is the initial state
+<% states_list.each_with_index do |state, index| %>
+      state :<%= state %><%= index == 0 ? ", initial: true" : "" %>
+<% end %>
+
+      # Events — define transitions between states
+      # event :activate, from: :<%= states_list[0] %>, to: :<%= states_list[1] || states_list[0] %>
+      # event :complete, from: :<%= states_list[1] || states_list[0] %>, to: :<%= states_list.last %>
+
+      # Guards — conditions that must be true for an event to fire
+      # guard :has_required_data, on: :activate do |record|
+      #   record.some_field.present?
+      # end
+
+      # Side effects — actions that run after a successful transition
+      # side_effect :notify_stakeholders, on: :activate do |record, transition|
+      #   # Your notification code here
+      # end
+    end
+  end
+end

data/lib/generators/fosm/app/templates/views/_form.html.erb.tt

@@ -0,0 +1,24 @@
+<%%= form_with model: record, url: record.new_record? ? fosm_<%= plural_name %>_path : fosm_<%= file_name %>_path(record), class: "space-y-4" do |f| %>
+  <%% if record.errors.any? %>
+    <div class="bg-red-50 border border-red-200 rounded p-3">
+      <p class="text-sm text-red-700 font-medium">Please fix the following errors:</p>
+      <ul class="text-sm text-red-600 list-disc list-inside mt-1">
+        <%% record.errors.full_messages.each do |msg| %>
+          <li><%%= msg %></li>
+        <%% end %>
+      </ul>
+    </div>
+  <%% end %>
+
+<% fields_for_migration.each do |field| %>
+  <div>
+    <%%= f.label :<%= field[:name] %>, class: "block text-sm font-medium text-gray-700 mb-1" %>
+    <%%= f.<%= field[:type] == "text" ? "text_area" : "text_field" %> :<%= field[:name] %>, class: "w-full border border-gray-200 rounded px-3 py-2 text-sm" %>
+  </div>
+<% end %>
+
+  <div class="flex gap-3 pt-2">
+    <%%= f.submit class: "bg-blue-600 text-white px-4 py-2 rounded text-sm hover:bg-blue-700" %>
+    <%%= link_to "Cancel", fosm_<%= plural_name %>_path, class: "text-sm text-gray-500 py-2" %>
+  </div>
+<%% end %>

data/lib/generators/fosm/app/templates/views/index.html.erb.tt

@@ -0,0 +1,37 @@
+<div class="p-6 space-y-4">
+  <div class="flex items-center justify-between">
+    <h1 class="text-2xl font-bold text-gray-900"><%= class_name.pluralize.humanize %></h1>
+    <%%= link_to "New <%= class_name.humanize %>", new_fosm_<%= file_name %>_path, class: "bg-blue-600 text-white px-4 py-2 rounded text-sm hover:bg-blue-700" %>
+  </div>
+
+  <table class="w-full bg-white border border-gray-200 rounded-lg text-sm">
+    <thead class="bg-gray-50 text-gray-500 text-xs uppercase">
+      <tr>
+        <th class="px-4 py-2 text-left">ID</th>
+        <th class="px-4 py-2 text-left">State</th>
+<% fields_for_migration.first(3).each do |field| %>
+        <th class="px-4 py-2 text-left"><%= field[:name].humanize %></th>
+<% end %>
+        <th class="px-4 py-2 text-left">Created</th>
+        <th class="px-4 py-2 text-left">Actions</th>
+      </tr>
+    </thead>
+    <tbody class="divide-y divide-gray-100">
+      <%% @records.each do |record| %>
+        <tr>
+          <td class="px-4 py-2 text-gray-600"><%%= record.id %></td>
+          <td class="px-4 py-2">
+            <span class="text-xs font-medium bg-gray-100 text-gray-700 px-2 py-0.5 rounded"><%%= record.state %></span>
+          </td>
+<% fields_for_migration.first(3).each do |field| %>
+          <td class="px-4 py-2 text-gray-700"><%%= record.<%= field[:name] %> %></td>
+<% end %>
+          <td class="px-4 py-2 text-gray-400"><%%= record.created_at.strftime("%b %d, %Y") %></td>
+          <td class="px-4 py-2">
+            <%%= link_to "View", fosm_<%= file_name %>_path(record), class: "text-blue-600 hover:underline text-xs" %>
+          </td>
+        </tr>
+      <%% end %>
+    </tbody>
+  </table>
+</div>

data/lib/generators/fosm/app/templates/views/new.html.erb.tt

@@ -0,0 +1,4 @@
+<div class="p-6 max-w-lg space-y-6">
+  <h1 class="text-2xl font-bold text-gray-900">New <%= class_name.humanize %></h1>
+  <%%= render "form", record: @record %>
+</div>

data/lib/generators/fosm/app/templates/views/show.html.erb.tt

@@ -0,0 +1,57 @@
+<div class="p-6 max-w-2xl space-y-6">
+  <div class="flex items-center gap-3">
+    <%%= link_to "← Back", fosm_<%= plural_name %>_path, class: "text-sm text-blue-600 hover:underline" %>
+  </div>
+
+  <div class="bg-white border border-gray-200 rounded-lg p-5 space-y-4">
+    <div class="flex items-center justify-between">
+      <h1 class="text-xl font-bold text-gray-900"><%= class_name.humanize %> #<%%= @record.id %></h1>
+      <span class="text-sm font-medium bg-blue-50 text-blue-700 px-3 py-1 rounded-full"><%%= @record.state %></span>
+    </div>
+
+<% fields_for_migration.each do |field| %>
+    <div>
+      <span class="text-xs text-gray-500 uppercase tracking-wide"><%= field[:name].humanize %></span>
+      <p class="text-gray-900 mt-0.5"><%%= @record.<%= field[:name] %> || "—" %></p>
+    </div>
+<% end %>
+  </div>
+
+  <%% if @record.available_events.any? %>
+    <div class="bg-white border border-gray-200 rounded-lg p-5">
+      <h2 class="font-semibold text-gray-900 mb-3">Available Actions</h2>
+      <div class="flex gap-2 flex-wrap">
+        <%% @record.available_events.each do |event| %>
+          <%%= button_to event.to_s.humanize,
+                         fire_event_fosm_<%= file_name %>_path(@record),
+                         params: { event: event },
+                         method: :post,
+                         class: "text-sm bg-gray-800 text-white px-4 py-2 rounded hover:bg-gray-700" %>
+        <%% end %>
+      </div>
+    </div>
+  <%% end %>
+
+  <div class="bg-white border border-gray-200 rounded-lg p-5">
+    <h2 class="font-semibold text-gray-900 mb-3">Transition History</h2>
+    <%% transitions = Fosm::TransitionLog.for_record("Fosm::<%= class_name %>", @record.id).recent %>
+    <%% if transitions.any? %>
+      <div class="space-y-2">
+        <%% transitions.each do |t| %>
+          <div class="text-sm flex items-center gap-2">
+            <span class="text-orange-600"><%%= t.from_state %></span>
+            <span class="text-gray-400">&rarr;</span>
+            <span class="text-green-600"><%%= t.to_state %></span>
+            <span class="text-gray-400">via <%%= t.event_name %></span>
+            <%% if t.actor_label.present? %>
+              <span class="text-gray-500">by <%%= t.actor_label %></span>
+            <%% end %>
+            <span class="text-gray-400 text-xs"><%%= t.created_at.strftime("%b %d %H:%M") %></span>
+          </div>
+        <%% end %>
+      </div>
+    <%% else %>
+      <p class="text-sm text-gray-400">No transitions yet.</p>
+    <%% end %>
+  </div>
+</div>

data/lib/tasks/fosm/rails_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :fosm_rails do
+#   # Task goes here
+# end