open-loam 0.1.0

data/lib/loam/open_api.rb

@@ -0,0 +1,194 @@
+require "json"
+
+module Loam
+  # Auto-generates an OpenAPI 3.1 document for the app's JSON API by
+  # INTROSPECTING what Loam already knows — the generated `Api::<Plural>Controller`s,
+  # each entity's columns/types, its exposed `FIELDS`, its custom fields, and that
+  # every endpoint is bearer-authenticated and tenant-scoped. No hand-written
+  # annotations, no external gem.
+  #
+  #   Loam::OpenApi.document   # => a Hash conforming to OpenAPI 3.1
+  #   Loam::OpenApi.markdown   # => a Markdown rendering
+  #
+  # The document describes the SHAPE of the API only — never tenant data. It is
+  # served at /admin/api_docs and exported by `bin/rails loam:openapi:export`.
+  module OpenApi
+    TYPE_MAP = {
+      "string" => { "type" => "string" }, "text" => { "type" => "string" },
+      "integer" => { "type" => "integer" }, "bigint" => { "type" => "integer" },
+      "float" => { "type" => "number" }, "decimal" => { "type" => "number" },
+      "boolean" => { "type" => "boolean" },
+      "date" => { "type" => "string", "format" => "date" },
+      "datetime" => { "type" => "string", "format" => "date-time" },
+      "json" => { "type" => "object" }, "jsonb" => { "type" => "object" }
+    }.freeze
+
+    TENANCY_NOTE = "Every endpoint is tenant-scoped by the bearer token: a caller only ever reads or " \
+                   "writes data in the token's OWN tenant — cross-tenant access is impossible.".freeze
+
+    module_function
+
+    def document
+      {
+        "openapi" => "3.1.0",
+        "info" => info,
+        "servers" => [ { "url" => "/api" } ],
+        "security" => [ { "bearerAuth" => [] } ],
+        "components" => { "securitySchemes" => security_schemes, "schemas" => schemas },
+        "paths" => paths,
+        "x-tenancy" => TENANCY_NOTE
+      }
+    end
+
+    # The Loam entities that have a generated JSON API controller. Anonymous
+    # subclasses (Class.new(Loam::TenantRecord), common in tests) have no name,
+    # so model_name would raise "Class name cannot be blank" — skip them: a
+    # nameless class has no controller or route to document anyway.
+    def api_entities
+      Rails.application.eager_load! if defined?(Rails) && Rails.respond_to?(:application)
+      Loam::TenantRecord.descendants
+                        .reject { |model| model.name.blank? }
+                        .select { |model| controller_for(model) }
+                        .sort_by(&:name)
+    end
+
+    def controller_for(model)
+      # model_name.plural handles uncountables ("equipment"), unlike route_key
+      # (which becomes "equipment_index").
+      "Api::#{model.model_name.plural.camelize}Controller".safe_constantize
+    end
+
+    def info
+      name = defined?(Rails) ? Rails.application.class.module_parent_name : "Loam"
+      {
+        "title" => "#{name} API",
+        "version" => "1.0.0",
+        "description" => "Auto-generated from the Loam entities. Bearer-token authenticated. #{TENANCY_NOTE}"
+      }
+    end
+
+    def security_schemes
+      { "bearerAuth" => { "type" => "http", "scheme" => "bearer",
+                          "description" => "A Loam::ApiToken — identifies one user in one tenant." } }
+    end
+
+    def schemas
+      api_entities.each_with_object({}) do |model, out|
+        out[model.name] = entity_schema(model)
+        out["#{model.name}Input"] = input_schema(model)
+      end
+    end
+
+    def entity_schema(model)
+      props = { "id" => { "type" => "integer", "readOnly" => true } }
+      exposed_fields(model).each { |field| props[field] = column_schema(model, field) }
+      custom_field_names(model).each { |name| props[name] = { "type" => "string", "description" => "custom field" } }
+      %w[created_at updated_at].each { |ts| props[ts] = { "type" => "string", "format" => "date-time", "readOnly" => true } }
+      { "type" => "object", "properties" => props }
+    end
+
+    # Request body: the writable, declared fields only — never id/tenant_id/
+    # timestamps. Field-level write access is enforced per the token's role at
+    # runtime (Loam::Policy), which a structural schema can't express per-role;
+    # noted in the description rather than emitting a schema per role.
+    def input_schema(model)
+      props = {}
+      exposed_fields(model).each { |field| props[field] = column_schema(model, field) }
+      custom_field_names(model).each { |name| props[name] = { "type" => "string" } }
+      {
+        "type" => "object",
+        "properties" => props,
+        "description" => "Field-level write access applies per the token's role — a field the role may not write is ignored."
+      }
+    end
+
+    def paths
+      api_entities.each_with_object({}) do |model, out|
+        plural = model.model_name.plural
+        ref = { "$ref" => "#/components/schemas/#{model.name}" }
+        input = { "$ref" => "#/components/schemas/#{model.name}Input" }
+
+        out["/#{plural}"] = {
+          "get" => operation("List #{plural}", "200" => array_response(ref)),
+          "post" => operation("Create a #{model.name}", body: input, "201" => object_response(ref), "422" => error_response("validation failed"))
+        }
+        out["/#{plural}/{id}"] = {
+          "parameters" => [ id_param ],
+          "get" => operation("Fetch a #{model.name}", "200" => object_response(ref), "404" => error_response("not found")),
+          "patch" => operation("Update a #{model.name}", body: input, "200" => object_response(ref), "422" => error_response("validation failed"), "404" => error_response("not found")),
+          "delete" => operation("Soft-delete a #{model.name}", "204" => { "description" => "deleted" }, "404" => error_response("not found"))
+        }
+      end
+    end
+
+    # ---- markdown ----
+
+    def markdown(doc = document)
+      lines = [ "# #{doc['info']['title']}", "", doc["info"]["description"], "", "**Auth:** bearer token. **Tenancy:** #{doc['x-tenancy']}", "" ]
+      doc["paths"].sort.each do |path, ops|
+        ops.each do |method, op|
+          next unless op.is_a?(Hash) && op["summary"]
+          lines << "## `#{method.upcase} /api#{path}` — #{op['summary']}"
+          lines << "Requires a bearer token. Responses: #{op['responses'].keys.join(', ')}."
+          lines << ""
+        end
+      end
+      lines.join("\n")
+    end
+
+    # ---- internals ----
+
+    def exposed_fields(model)
+      controller = controller_for(model)
+      return controller::FIELDS.map(&:to_s) if controller.const_defined?(:FIELDS)
+
+      # No declared FIELDS: fall back to columns, but NEVER surface an encrypted
+      # column or its blind-index `_hash` (same exclusion as Loam::Export).
+      encrypted = model.respond_to?(:loam_encrypted_attributes) ? model.loam_encrypted_attributes : []
+      blind = model.respond_to?(:loam_searchable_encrypted_attributes) ? model.loam_searchable_encrypted_attributes.map { |a| "#{a}_hash" } : []
+      model.column_names - plumbing(model) - encrypted - blind
+    end
+
+    def plumbing(model)
+      %w[id tenant_id created_at updated_at lock_version deleted_at custom_fields]
+    end
+
+    def column_schema(model, field)
+      column = model.columns_hash[field.to_s]
+      return { "type" => "string" } unless column # a custom field or virtual
+
+      TYPE_MAP.fetch(column.type.to_s, { "type" => "string" }).dup
+    end
+
+    def custom_field_names(model)
+      return [] unless model.respond_to?(:custom_field_definitions) && Loam::Current.tenant
+
+      model.custom_field_definitions.map(&:name)
+    rescue StandardError
+      []
+    end
+
+    def operation(summary, body: nil, **responses)
+      responses = { "401" => error_response("missing or invalid token") }.merge(responses)
+      op = { "summary" => summary, "responses" => responses }
+      if body
+        op["requestBody"] = { "required" => true, "content" => { "application/json" => { "schema" => body } } }
+      end
+      op
+    end
+
+    def object_response(ref) = { "description" => "ok", "content" => { "application/json" => { "schema" => ref } } }
+
+    def array_response(ref)
+      { "description" => "ok", "content" => { "application/json" => { "schema" => { "type" => "array", "items" => ref } } } }
+    end
+
+    def error_response(desc)
+      { "description" => desc, "content" => { "application/json" => { "schema" => { "type" => "object", "properties" => { "error" => { "type" => "string" } } } } } }
+    end
+
+    def id_param
+      { "name" => "id", "in" => "path", "required" => true, "schema" => { "type" => "integer" } }
+    end
+  end
+end

data/lib/loam/overrides.rb

@@ -0,0 +1,110 @@
+module Loam
+  # Disable or replace an entry in one of Loam's OWN keyed registries from an
+  # initializer — customization without forking the gem, and without
+  # monkeypatching. This is deliberately SMALL: Rails already handles structural
+  # overriding (shadow a view/controller by path, prepend a module). Overrides
+  # only covers the in-gem keyed registries, where path-shadowing doesn't reach:
+  #
+  #   Loam::Overrides.disable(:widgets, "open_progress")            # drop a built-in widget
+  #   Loam::Overrides.replace(:widgets, "audit_recent") { |actor| { kind: "count", value: 0 } }
+  #   Loam::Overrides.disable(:broadcast_events, "loam.progress.")  # stop pushing an event over SSE
+  #
+  # THE VALUE-ADD over raw monkeypatching: a stale override (a typo, or an entry
+  # that no longer exists) is caught at boot by `check!` and warned about, so a
+  # silently-ineffective override is visible instead of a mystery.
+  #
+  # Registries with a keyed API — :widgets, :broadcast_events — honor disable AND
+  # replace. Seams that are a single swappable object (Search.driver,
+  # EventStream.broadcaster) are replaced by assigning them directly; Overrides
+  # doesn't wrap those. Controllers/views/routes are NOT here — that's Rails'
+  # path-shadowing job (see docs).
+  module Overrides
+    DISABLED = :__loam_disabled__
+
+    class << self
+      def disable(registry, key)
+        store[registry.to_sym][key.to_s] = DISABLED
+      end
+
+      def replace(registry, key, &block)
+        raise ArgumentError, "replace needs a block" unless block
+
+        store[registry.to_sym][key.to_s] = block
+      end
+
+      def disabled?(registry, key)
+        store[registry.to_sym][key.to_s] == DISABLED
+      end
+
+      # The replacement block for a key, or nil (also nil when disabled).
+      def replacement(registry, key)
+        value = store[registry.to_sym][key.to_s]
+        value unless value == DISABLED || value.nil?
+      end
+
+      def entries(registry)
+        store[registry.to_sym]
+      end
+
+      def all
+        store
+      end
+
+      def reset!
+        @store = Hash.new { |hash, key| hash[key] = {} }
+      end
+
+      # For tests: capture and restore the process-global override state so a
+      # test's overrides don't leak (and the app's boot-time overrides survive).
+      def snapshot
+        store.each_with_object({}) { |(registry, keys), out| out[registry] = keys.dup }
+      end
+
+      def restore(snapshot)
+        reset!
+        snapshot.each { |registry, keys| store[registry].merge!(keys) }
+      end
+
+      # Overrides whose key isn't present in the live registry — a typo or a
+      # removed entry. Only registries we can introspect are checked; others are
+      # skipped (returned as safe). Returns [[registry, key], ...].
+      def stale
+        store.flat_map do |registry, keys|
+          known = known_keys(registry)
+          next [] if known.nil?
+
+          keys.keys.reject { |key| known.include?(key) }.map { |key| [ registry, key ] }
+        end
+      end
+
+      # Warn (once, at boot) about every stale override, and return them.
+      def check!
+        found = stale
+        found.each do |registry, key|
+          message = "[loam] stale override: #{registry} has no entry #{key.inspect} to disable/replace — the override is doing nothing."
+          logger ? logger.warn(message) : warn(message)
+        end
+        found
+      end
+
+      private
+
+      def store
+        @store ||= Hash.new { |hash, key| hash[key] = {} }
+      end
+
+      # The live keys of an introspectable registry, or nil when we can't tell.
+      def known_keys(registry)
+        case registry.to_sym
+        when :widgets then Loam::Widgets.keys
+        when :broadcast_events then Loam.broadcast_events
+        when :scheduler then defined?(Loam::Scheduler) ? Loam::Scheduler.registered.map { |d| d[:key] } : nil
+        end
+      end
+
+      def logger
+        Rails.logger if defined?(Rails) && Rails.respond_to?(:logger)
+      end
+    end
+  end
+end

data/lib/loam/pending_actions.rb

@@ -0,0 +1,60 @@
+module Loam
+  # Staging and reviewing gated mutations (see Loam::PendingAction).
+  #
+  #   pending = Loam::PendingActions.stage(
+  #     summary: "Raise the excavator's daily rate to 1100",
+  #     on: equipment, action: :update, changes: { daily_rate: 1100 }
+  #   )
+  #   pending.preview            # => { "daily_rate" => { "from" => 950, "to" => 1100 } }
+  #   pending.approve!(by: manager)   # role-gated; executes the change
+  #
+  # `stage` NEVER touches the target — it only records the intent. Loam does not
+  # intercept Active Record globally (that would be fragile and out of scope);
+  # this is the primitive a confirm-mode write path calls instead of saving.
+  module PendingActions
+    class << self
+      def stage(summary:, on:, action:, changes: {}, idempotency_key: nil, actor: Loam::Current.actor)
+        target_type, target_id = resolve_target(on)
+        changes = changes.transform_keys(&:to_s)
+        key = idempotency_key || compute_key(target_type, target_id, action, changes)
+
+        # The same proposal staged twice collapses to one row — but only a still
+        # PENDING one. A rejected or executed proposal with this key may be
+        # re-staged as a fresh pending row (the partial index allows the coexist).
+        existing = Loam::PendingAction.pending.find_by(idempotency_key: key)
+        return existing if existing
+
+        Loam::PendingAction.create!(
+          actor_id: actor&.id,
+          action_type: action.to_s,
+          target_type: target_type,
+          target_id: target_id,
+          changeset: changes,
+          summary: summary,
+          idempotency_key: key
+        )
+      rescue ActiveRecord::RecordNotUnique
+        # Lost a concurrent double-stage race — return the pending row that won.
+        Loam::PendingAction.pending.find_by!(idempotency_key: key)
+      end
+
+      private
+
+      # A class stages a create (no target id yet); a record stages a change to
+      # itself.
+      def resolve_target(on)
+        on.is_a?(Class) ? [ on.name, nil ] : [ on.class.name, on.id ]
+      end
+
+      # A KEYED (per-tenant HMAC), not a plain, digest of the proposal: a raw
+      # SHA-256 of a low-entropy value (a tax id, an SSN) in an indexed column
+      # would be a brute-force oracle from a DB dump. Reuses L-901's blind index.
+      # Determinism relies on `changes` insertion order — the same caller yields
+      # the same key; a reordered hash is treated as a different proposal.
+      def compute_key(target_type, target_id, action, changes)
+        payload = [ target_type, target_id, action, changes.to_json ].join("|")
+        Loam::Encryption.blind_index_scoped(payload, "tenant/#{Loam.tenant!.id}")
+      end
+    end
+  end
+end

data/lib/loam/permissions.rb

@@ -0,0 +1,79 @@
+module Loam
+  # Feature-string permissions with wildcards (L-705) — a fine-grained capability
+  # layer that sits UNDER the coarse role. Roles answer "manager or clerk";
+  # permissions answer "may this role do `equipment.edit`" without inventing a new
+  # role for every distinction. Orthogonal to Loam::Policy (which gates field-level
+  # writes on a record) and to Loam::Features (a per-tenant capability switch).
+  #
+  # Declared once, in the initializer (like broadcast_events / scheduler defaults):
+  #
+  #   Loam::Permissions.configure do
+  #     role :admin,   allow: "*"                              # everything
+  #     role :manager, allow: %w[equipment.* damage_report.* billing.read]
+  #     role :clerk,   allow: %w[equipment.read damage_report.create]
+  #   end
+  #
+  #   Loam::Permissions.allow?(:clerk, "equipment.read")  # => true
+  #   Loam::Permissions.allow?(:clerk, "equipment.edit")  # => false
+  #   Loam.can?("equipment.edit")                          # for the current actor's role
+  #
+  # DENY BY DEFAULT: a role with no matching grant (or no grants at all) is denied.
+  #
+  # Wildcards: `*` grants everything; a trailing `.*` is a prefix ("equipment.*"
+  # matches "equipment.read" and "equipment.anything.deep", and "equipment"
+  # itself); anything else is an exact match. (Deliberately not a full glob —
+  # prefix + all covers the real cases; a mid-string `*` is not special.)
+  module Permissions
+    class << self
+      def configure(&block)
+        DSL.new.instance_eval(&block)
+        registry
+      end
+
+      # Grant one role a pattern or list of patterns (additive).
+      def role(name, allow:)
+        registry[name.to_s] ||= []
+        registry[name.to_s].concat(Array(allow).map(&:to_s)).uniq!
+        registry[name.to_s]
+      end
+
+      def granted(role) = registry[role.to_s] || []
+
+      def allow?(role, permission)
+        return false if role.nil?
+
+        granted(role).any? { |pattern| matches?(pattern, permission.to_s) }
+      end
+
+      # THE wildcard rule, in one place.
+      def matches?(pattern, permission)
+        pattern = pattern.to_s
+        return true if pattern == "*"
+
+        if pattern.end_with?(".*")
+          prefix = pattern[0..-2]           # "equipment." (keep the dot)
+          permission == pattern[0..-3] || permission.start_with?(prefix)
+        else
+          permission == pattern
+        end
+      end
+
+      def reset!
+        @registry = {}
+      end
+
+      private
+
+      def registry
+        @registry ||= {}
+      end
+    end
+
+    # Tiny DSL so `configure { role ... }` reads well without a receiver.
+    class DSL
+      def role(name, allow:)
+        Loam::Permissions.role(name, allow: allow)
+      end
+    end
+  end
+end

data/lib/loam/perspectives.rb

@@ -0,0 +1,62 @@
+module Loam
+  # Reading the saved views (Loam::Perspective) a user may see for an entity.
+  #
+  #   Loam::Perspectives.visible_to("Equipment", user: current_actor)   # pick list
+  #   Loam::Perspectives.default_for("Equipment", user: current_actor)  # the applicable default
+  #   Loam::Perspectives.resolve("Equipment", user:, id: params[:perspective_id])
+  #
+  # Every query is tenant-scoped by Loam::Perspective. The membership role used
+  # for role-shared views is the user's role in the CURRENT tenant.
+  module Perspectives
+    class << self
+      # The views this user may see for an entity: their own private ones, the
+      # role-shared ones matching their membership role, and the tenant-wide
+      # ones. Default(s) first, then by name. Named `visible_to` rather than
+      # `for` so it does not read like Loam::Policy.for (which builds a policy).
+      def visible_to(entity_type, user:)
+        base = Loam::Perspective.where(entity_type: entity_type.to_s)
+        role = membership_role(user)
+
+        # Build the OR chain on UNORDERED relations — `.or` refuses to combine
+        # relations that carry an order — then order once at the end.
+        visible = base.where(visibility: "private", owner_id: user&.id)
+                      .or(base.where(visibility: "tenant"))
+        visible = visible.or(base.where(visibility: "role", role: role)) if role
+
+        visible.order(is_default: :desc, name: :asc)
+      end
+
+      # The applicable default, most specific audience first: the user's own
+      # private default, else a role default, else a tenant default, else nil.
+      def default_for(entity_type, user:)
+        defaults = visible_to(entity_type, user: user).select(&:is_default?)
+        defaults.min_by { |perspective| VISIBILITY_PRIORITY.fetch(perspective.visibility, 9) }
+      end
+
+      # The view to apply for an index request: the one explicitly picked (if the
+      # user may see it), otherwise the default. nil means "no saved view".
+      def resolve(entity_type, user:, id: nil)
+        # "none" is the picker's explicit "show everything" — it must bypass the
+        # default, or a tenant default would be inescapable from the UI.
+        return nil if id == "none"
+
+        if id.present?
+          picked = visible_to(entity_type, user: user).find_by(id: id)
+          return picked if picked
+        end
+
+        default_for(entity_type, user: user)
+      end
+
+      private
+
+      VISIBILITY_PRIORITY = { "private" => 0, "role" => 1, "tenant" => 2 }.freeze
+
+      def membership_role(user)
+        return nil unless user
+
+        Loam::Membership.find_by(user_id: user.id)&.role
+      end
+    end
+  end
+end

data/lib/loam/policy.rb

@@ -0,0 +1,106 @@
+module Loam
+  # Base policy. One policy class per entity, one instance per (actor, record)
+  # pair. Action checks (read?/create?/update?/destroy?) default to "any member
+  # of the current tenant"; field-level write access is declared, not coded:
+  #
+  #   class EquipmentPolicy < Loam::Policy
+  #     field :daily_rate, writable: [:manager]
+  #   end
+  #
+  # Roles come from Loam::Membership (actor + current tenant -> role).
+  class Policy
+    class << self
+      def field_rules
+        @field_rules ||= {}
+      end
+
+      def field(name, writable: nil, readable: nil)
+        field_rules[name.to_sym] = { writable: writable, readable: readable }
+      end
+
+      def for(record)
+        policy_class = "#{record.class.name}Policy".safe_constantize
+        raise Error, "No policy defined for #{record.class.name} (expected #{record.class.name}Policy)" unless policy_class
+
+        policy_class.new(Loam::Current.actor, record)
+      end
+    end
+
+    attr_reader :actor, :record
+
+    def initialize(actor, record)
+      @actor = actor
+      @record = record
+    end
+
+    def role
+      return nil unless actor
+
+      @role ||= Loam::Membership.find_by(user_id: actor.id)&.role&.to_sym
+    end
+
+    def member? = role.present?
+
+    def read? = member?
+    def create? = member?
+    def update? = member?
+    def destroy? = member?
+
+    # Field-level check: fields without a declared rule are writable by any
+    # member; fields with `writable:` only by the listed roles.
+    def writable?(field_name)
+      rule = self.class.field_rules[field_name.to_sym]
+      return member? if rule.nil? || rule[:writable].nil?
+
+      Array(rule[:writable]).map(&:to_sym).include?(role)
+    end
+
+    def permitted_fields(field_names)
+      field_names.select { |f| writable?(f) }
+    end
+
+    # Field-level READ check (used by CSV export): a field with no `readable:`
+    # rule is readable by any member; with one, only by the listed roles.
+    def readable?(field_name)
+      rule = self.class.field_rules[field_name.to_sym]
+      return member? if rule.nil? || rule[:readable].nil?
+
+      Array(rule[:readable]).map(&:to_sym).include?(role)
+    end
+
+    def readable_fields(field_names)
+      field_names.select { |f| readable?(f) }
+    end
+
+    # Same semantics as the static `field writable:` declaration, but for a
+    # runtime Loam::FieldDefinition (see Loam::CustomFields): no
+    # writable_roles recorded means any member may write it.
+    def custom_field_writable?(field_name)
+      return false unless member?
+
+      definition = record.class.custom_field_definitions.find_by(name: field_name.to_s)
+      return false unless definition
+
+      definition.writable_roles.blank? || definition.writable_roles.map(&:to_sym).include?(role)
+    end
+
+    def permitted_custom_fields(field_names)
+      field_names.select { |f| custom_field_writable?(f) }
+    end
+
+    # Read counterpart of custom_field_writable?: a runtime field with no
+    # readable_roles is readable by any member; with some, only by those roles.
+    def custom_field_readable?(field_name)
+      return false unless member?
+
+      definition = record.class.custom_field_definitions.find_by(name: field_name.to_s)
+      return false unless definition
+
+      definition.readable_by?(role)
+    end
+
+    def readable_custom_fields(field_names)
+      field_names.select { |f| custom_field_readable?(f) }
+    end
+  end
+end

data/lib/loam/progress.rb

@@ -0,0 +1,31 @@
+module Loam
+  # Entry point for progress tracking. Start a job, then drive it through the
+  # returned Loam::ProgressJob:
+  #
+  #   progress = Loam::Progress.start(name: "Reindex", total: equipment.count)
+  #   equipment.find_each do |record|
+  #     break if progress.cancelled?   # cooperative cancel
+  #     do_work(record)
+  #     progress.advance                # throttled SSE push
+  #   end
+  #   progress.complete!
+  #
+  # The job is created in the current tenant (and stamped with the current
+  # actor), so it is only visible and streamable there. In a background job,
+  # establish the tenant with Loam.as_tenant first, like the webhook/digest jobs.
+  module Progress
+    module_function
+
+    def start(name:, total:, key: nil)
+      Loam::ProgressJob.create!(
+        key: key,
+        name: name,
+        total: total.to_i,
+        completed: 0,
+        status: "running",
+        actor_id: Loam.actor&.id,
+        started_at: Time.current
+      )
+    end
+  end
+end