command_tower 0.16.0 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e983f8f191ccb75948cdad73067d1cd43b7b1e5a8a3e0d34fc0130a76c313da
-  data.tar.gz: 5ef89ea100c06425afe3aee6f87b8b71503e4d28be6a4ff6e309af8a5b02c83f
+  metadata.gz: 8b75ad05bfb533351f79dcf7c242e201a225d86cedd0a3f97358a01e91cbb830
+  data.tar.gz: e5e89fe1645e781155862a124f37c625ad0804593959d118d5e8f2c523d629a2
 SHA512:
-  metadata.gz: 6555727a8b33efc95493ecdeec48067e39c8ee9eb4f1750c8fd183599a8d41bf1e763d538d379d0be7888697e6f09ca0795ebb643817d5aea2c548c61cd867f6
-  data.tar.gz: ca51dafb697b03848b2509f16660df1e9e349f325a01da7d589300ac7db0ee087df33c08d46194a97e60ae6cbc984de8bcbf1fbc65f41d7bd31f31013d64add4
+  metadata.gz: fdbc47eafe86db87598541f3c4cbf86a4b23876e321eb137bef5f2a5d9e9b04f2adfb2d38c822b1980bfd150384443717eab03980442975aa93318fb909e2473
+  data.tar.gz: d374ca61c7fef265974aa71ed8c9bee9c98401efb6328cc240b5685997c8fbf9c1e00928fd2bf2bdd0879e7a013acb0a46200a14133307df57b66da0a44ec391

data/README.md

@@ -8,21 +8,21 @@ The engine is opinionated and configurable. Architecture follows a stable layer
 
 ## Quick start
 
+**New Rails host?** Start with [Bootstrap a new host](docs/bootstrap/README.md) (Docker + Make only; local bring-up, not deployment).
+
 ```ruby
 # Gemfile
 gem "command_tower"
 ```
 
 ```bash
-bundle install
-bin/rails command_tower:install
-bin/rails db:migrate
-bin/rails command_tower:doctor
+make bundle
+make rails ARGS='command_tower:install'
+make migrate
+make doctor
 ```
 
-Full install, upgrade, configuration, and troubleshooting: [Initializing CommandTower](docs/initializing.md).
-
-After install, complete RBAC, feature gates, and a Me smoke check: [Host integration guide](docs/host_integration_guide.md) (**start here for a new Rails host**).
+Those `make` targets run inside Compose. Do not run `bundle` or `bin/rails` on the Mac. Full install contract: [Initializing CommandTower](docs/initializing.md).
 
 ## Architecture
 
@@ -40,7 +40,7 @@ See [Architecture](docs/architecture.md) and [ServiceBase](app/services/command_
 
 | Guide | Purpose |
 |-------|---------|
-| [Host integration](docs/host_integration_guide.md) | **Start here** — step-by-step new Rails host path |
+| [Bootstrap a new host](docs/bootstrap/README.md) | **Start here** — ordered Docker/Make new-host path |
 | [Upgrades](docs/upgrades/README.md) | Release upgrade summaries (see [0.11.0](docs/upgrades/0.11.0.md)) |
 | [Initializing](docs/initializing.md) | Install, configure, migrate, doctor, upgrades |
 | [Testing](docs/testing.md) | Shared FactoryBot / `CommandTower::Testing` |

data/app/controllers/command_tower/application_controller.rb

@@ -3,6 +3,7 @@
 module CommandTower
   class ApplicationController < ActionController::API
     include CommandTower::Execution::HttpBoundary
+    include CommandTower::Execution::ClientCompatibilityBoundary
 
     AUTHENTICATION_HEADER = CommandTower::Jwt::AuthorizationHelper::AUTHENTICATION_HEADER
     AUTHENTICATION_EXPIRE_HEADER = CommandTower::Jwt::AuthorizationHelper::AUTHENTICATION_EXPIRE_HEADER

data/app/controllers/command_tower/me/inbox_controller.rb

@@ -18,6 +18,22 @@ module CommandTower
         ))
       end
 
+      def conversation
+        deserialized = CommandTower::Deserializers::Messaging::Inbox::ConversationDeserializer.call(params)
+        return render_deserializer_errors unless deserialized.success?
+
+        input = deserialized.input
+        render_application_result(CommandTower::Workflows::Messaging::Inbox::ConversationWorkflow.call(
+          user: current_user,
+          key: input.key,
+          scope: input.scope,
+          around: input.around,
+          before_id: input.before_id,
+          after_id: input.after_id,
+          limit: input.limit,
+        ))
+      end
+
       def show
         run_item_workflow(CommandTower::Workflows::Messaging::Inbox::ShowWorkflow)
       end

data/app/controllers/concerns/command_tower/execution/client_compatibility_boundary.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Execution
+    # Runs the client-version-compatibility check for every JSON request,
+    # before any authentication/authorization filter. Transport-only: it
+    # invokes exactly one workflow and renders its result — all decisioning
+    # lives in `Workflows::ClientCompatibility::EvaluateWorkflow` /
+    # `Services::ClientCompatibility::Evaluate` (authority §10).
+    #
+    # Hosts that need to exempt a controller (e.g. a healthz-style endpoint)
+    # do so with `skip_before_action :evaluate_client_compatibility!`.
+    module ClientCompatibilityBoundary
+      extend ActiveSupport::Concern
+
+      included do
+        include CommandTower::Api::ApplicationResponseRenderer
+        before_action :evaluate_client_compatibility!
+      end
+
+      private
+
+      def evaluate_client_compatibility!
+        result = CommandTower::Workflows::ClientCompatibility::EvaluateWorkflow.call(
+          request: request,
+          controller_class: self.class,
+          action_name: action_name
+        )
+
+        unless result.success?
+          render_application_result(result)
+          return false
+        end
+
+        true
+      end
+    end
+  end
+end

data/app/deserializers/command_tower/deserializers/messaging/inbox.rb

@@ -37,6 +37,91 @@ module CommandTower
           end
         end
 
+        class ConversationDeserializer < CommandTower::Deserializers::ApplicationDeserializer
+          Input = Data.define(:key, :scope, :around, :before_id, :after_id, :limit)
+          ALLOWED_SCOPES = %w[inbox archived].freeze
+          OLDEST_UNREAD = "oldest_unread"
+
+          def call(params)
+            key = params[:key]
+            key = key.strip if key.is_a?(String)
+            return failure(errors: { message: "invalid_key" }) if !key.is_a?(String) || key.empty?
+
+            scope = params[:scope].presence || "inbox"
+            return failure(errors: { message: "invalid_scope" }) unless scope.is_a?(String) && ALLOWED_SCOPES.include?(scope.strip)
+
+            around = present_param(params[:around])
+            before_id = present_param(params[:before])
+            after_id = present_param(params[:after])
+            modes = [around, before_id, after_id].count { |value| !value.nil? }
+            return failure(errors: { message: "invalid_window" }) if modes > 1
+
+            if modes.zero?
+              return failure(errors: { message: "invalid_limit" }) if present_param(params[:limit])
+
+              return success(Input.new(key:, scope: scope.strip, around: nil, before_id: nil, after_id: nil, limit: nil))
+            end
+
+            parsed_around = nil
+            parsed_before = nil
+            parsed_after = nil
+            if around
+              parsed_around = parse_around(around)
+              return failure(errors: { message: "invalid_around" }) if parsed_around.nil?
+            elsif before_id
+              parsed_before = positive_integer(before_id)
+              return failure(errors: { message: "invalid_cursor" }) if parsed_before.nil?
+            else
+              parsed_after = positive_integer(after_id)
+              return failure(errors: { message: "invalid_cursor" }) if parsed_after.nil?
+            end
+
+            limit = window_limit(params[:limit])
+            return failure(errors: { message: "invalid_limit" }) if limit.nil?
+
+            success(Input.new(
+              key:,
+              scope: scope.strip,
+              around: parsed_around,
+              before_id: parsed_before,
+              after_id: parsed_after,
+              limit:,
+            ))
+          end
+
+          private
+
+          def present_param(raw)
+            return if raw.nil?
+            return if raw.is_a?(String) && raw.strip.empty?
+
+            raw
+          end
+
+          def parse_around(raw)
+            value = raw.is_a?(String) ? raw.strip : raw
+            return OLDEST_UNREAD if value == OLDEST_UNREAD
+
+            positive_integer(value)
+          end
+
+          def window_limit(raw)
+            return CommandTower::Messaging::Inbox::Reader::WINDOW_LIMIT unless present_param(raw)
+
+            value = positive_integer(raw)
+            return if value.nil? || value > CommandTower::Messaging::Inbox::Reader::WINDOW_LIMIT
+
+            value
+          end
+
+          def positive_integer(raw)
+            value = raw.is_a?(Integer) ? raw : (Integer(raw, 10) if raw.is_a?(String) && /\A\d+\z/.match?(raw.strip))
+            value if value&.positive?
+          rescue ArgumentError
+            nil
+          end
+        end
+
         class ShowDeserializer < CommandTower::Deserializers::ApplicationDeserializer
           Input = Data.define(:inbox_item_id)
 

data/app/errors/command_tower/errors/client_update_required_error.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Errors
+    # Hard client-version incompatibility (authority §14). Deliberately NOT
+    # registered in `SessionErrorStatus` — its HTTP status (426) is set
+    # directly by `Workflows::ClientCompatibility::EvaluateWorkflow`, not
+    # derived from that closed 401/403/412 mapping table.
+    class ClientUpdateRequiredError < ApplicationError
+      def initialize(details: {})
+        super(details:)
+      end
+
+      def code
+        "client_update_required"
+      end
+
+      def message
+        "Client update required"
+      end
+
+      def log_level
+        :warn
+      end
+    end
+  end
+end

data/app/jobs/command_tower/messaging/communications/produce_recipient_job.rb

@@ -16,6 +16,8 @@ module CommandTower
             body: attrs.fetch("body"),
             platform_enabled_channels: Array(attrs["platform_enabled_channels"]),
             metadata: attrs["metadata"],
+            conversation_key: attrs["conversation_key"],
+            conversation_title: attrs["conversation_title"],
           )
         end
       end

data/app/models/command_tower/messaging/communication.rb

@@ -30,10 +30,23 @@ module CommandTower
                dependent: :destroy,
                inverse_of: :communication
 
+      # Text column. The snapshot column uses the JSON attribute caster below
+      # instead of this coder. A second serialize pass would store a JSON
+      # string inside a JSON document on MySQL.
       serialize :metadata, coder: JSON, type: Hash
 
+      # MariaDB reports JSON columns as LONGTEXT. The text caster would write
+      # a Ruby hash string and fail `json_valid`. Forcing the JSON caster
+      # writes one JSON document on MySQL and on MariaDB.
+      attribute :inbox_presentation_snapshot, :json
+
+      CONVERSATION_KEY_FORMAT = /\A[A-Za-z0-9][A-Za-z0-9._:-]{0,127}\z/
+
       validates :notification_type_key, :title, :body, presence: true
       validates :execution_handoff_status, presence: true
+      validate :conversation_identity_is_a_pair
+
+      before_validation :normalize_conversation_identity
 
       scope :needing_handoff_recovery, lambda { |grace_before:|
         where(status: STATUS_ACCEPTED, execution_handoff_status: HANDOFF_RECOVERABLE_STATUSES)
@@ -55,6 +68,24 @@ module CommandTower
       def handoff_recoverable?
         HANDOFF_RECOVERABLE_STATUSES.include?(execution_handoff_status)
       end
+
+      private
+
+      def normalize_conversation_identity
+        self.conversation_key = nil if conversation_key.blank?
+        self.conversation_title = nil if conversation_title.blank?
+      end
+
+      def conversation_identity_is_a_pair
+        if conversation_key.present? ^ conversation_title.present?
+          errors.add(:conversation_key, "must be provided with a title")
+          errors.add(:conversation_title, "must be provided with a key")
+        end
+        return if conversation_key.blank?
+        return if conversation_key.match?(CONVERSATION_KEY_FORMAT)
+
+        errors.add(:conversation_key, "is invalid")
+      end
     end
   end
 end

data/app/serializers/command_tower/serializers/messaging/inbox.rb

@@ -4,6 +4,49 @@ module CommandTower
   module Serializers
     module Messaging
       module Inbox
+        class EntrySerializer
+          def self.serialize(entry)
+            {
+              kind: entry.fetch(:kind),
+              id: entry.fetch(:id),
+              title: entry.fetch(:title),
+              preview: entry[:preview],
+              activityAt: entry.fetch(:activity_at)&.iso8601,
+              createdAt: entry.fetch(:created_at)&.iso8601,
+              messageCount: entry.fetch(:message_count),
+              unreadCount: entry.fetch(:unread_count),
+              read: entry.fetch(:read),
+              inboxItemIds: entry.fetch(:inbox_item_ids),
+            }
+          end
+        end
+
+        class ConversationSerializer
+          def self.serialize(conversation)
+            payload = {
+              scope: conversation.fetch(:scope),
+              subject: conversation.fetch(:subject),
+              messageCount: conversation.fetch(:message_count),
+              unreadCount: conversation.fetch(:unread_count),
+              inboxItemIds: conversation.fetch(:inbox_item_ids),
+              messages: conversation.fetch(:messages).map { |message| DetailSerializer.serialize(message) },
+            }
+            window = conversation[:window]
+            payload[:window] = serialize_window(window) if window
+            payload
+          end
+
+          def self.serialize_window(window)
+            {
+              anchorInboxItemId: window[:anchor_inbox_item_id],
+              hasBefore: window[:has_before],
+              hasAfter: window[:has_after],
+              beforeCursor: window[:before_cursor],
+              afterCursor: window[:after_cursor],
+            }
+          end
+        end
+
         class ItemSerializer
           def self.serialize(item)
             { id: item.fetch(:id), title: item.fetch(:title), status: item.fetch(:status),
@@ -16,7 +59,8 @@ module CommandTower
           def self.serialize(item)
             ItemSerializer.serialize(item).merge(
               body: item.fetch(:body), metadata: item[:metadata],
-              notificationTypeKey: item.fetch(:notification_type_key)
+              notificationTypeKey: item.fetch(:notification_type_key),
+              content: item.fetch(:content)
             )
           end
         end

data/app/services/command_tower/email_theme/resolver.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module EmailTheme
+    # Internal rendering-time collaborator (not a Service/Workflow/Controller).
+    #
+    # Assembles the full semantic token set an email template needs: the
+    # visual tokens from CommandTower.config.email_theme plus the identity
+    # tokens CommandTower already exposes (config.application). Shared by
+    # Messaging email templates and, later, CT's own auth mail templates —
+    # hence its own top-level namespace rather than living under
+    # Messaging::Rendering.
+    #
+    # No template calls this yet (Rich Messaging Strategy §12 steps C/D are
+    # separate, later slices). This is deliberately not a
+    # CommandTower::Services::ApplicationService: it takes no arguments,
+    # performs no I/O, and cannot fail under normal config state — there is
+    # nothing to validate and nothing to fail. Mirrors
+    # Messaging::Rendering::TemplateResolver's own documented exemption.
+    class Resolver
+      class << self
+        def resolve
+          new.resolve
+        end
+      end
+
+      def resolve
+        theme = CommandTower.config.email_theme
+        {
+          canvas_background: theme.canvas_background,
+          surface_background: theme.surface_background,
+          surface_border: theme.surface_border,
+          primary_text: theme.primary_text,
+          body_text: theme.body_text,
+          muted_text: theme.muted_text,
+          accent: theme.accent,
+          text_on_accent: theme.text_on_accent,
+          primary_action: theme.primary_action,
+          product_name: CommandTower.app_name_for_comms,
+          product_url: CommandTower.config.application.composed_url
+        }.freeze
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/accept/coordinator.rb

@@ -19,7 +19,9 @@ module CommandTower
           metadata: nil,
           preference_state: nil,
           platform_enabled_channels:,
-          message_overrides: nil
+          message_overrides: nil,
+          conversation_key: nil,
+          conversation_title: nil
         )
           @recipient_id = recipient_id
           @notification_type_key = notification_type_key
@@ -30,6 +32,8 @@ module CommandTower
           @preference_state = preference_state
           @platform_enabled_channels = platform_enabled_channels
           @message_overrides = message_overrides
+          @conversation_key = conversation_key
+          @conversation_title = conversation_title
         end
 
         def call
@@ -43,6 +47,8 @@ module CommandTower
             preference_state: @preference_state,
             platform_enabled_channels: @platform_enabled_channels,
             message_overrides: @message_overrides,
+            conversation_key: @conversation_key,
+            conversation_title: @conversation_title,
           }
 
           OperationLogger.around(request:) do
@@ -141,9 +147,18 @@ module CommandTower
         rescue ActiveRecord::RecordNotUnique => error
           resolve_record_not_unique!(error, fingerprint)
         rescue ActiveRecord::RecordInvalid => e
+          if conversation_pair_invalid?(e)
+            raise ValidationError, e.record.errors.full_messages.join("; ")
+          end
+
           raise PersistenceError, e.message
         end
 
+        def conversation_pair_invalid?(error)
+          names = error.record.errors.attribute_names.map(&:to_sym)
+          names.any? && (names - %i[conversation_key conversation_title]).empty?
+        end
+
         def resolve_record_not_unique!(error, fingerprint)
           existing = find_by_namespace
           if existing

data/app/services/command_tower/messaging/accept/persister.rb

@@ -28,7 +28,10 @@ module CommandTower
               title: @request.fetch(:title),
               body: @request.fetch(:body),
               metadata: freeze_metadata(@request[:metadata]),
+              conversation_key: @request[:conversation_key],
+              conversation_title: @request[:conversation_title],
             )
+            assign_presentation_snapshot!(communication)
 
             Messaging::DestinationPlan.create!(
               communication:,
@@ -56,6 +59,16 @@ module CommandTower
 
         private
 
+        def assign_presentation_snapshot!(communication)
+          snapshot = CommandTower::Messaging::Rendering::InboxPresentationSnapshot.capture(
+            communication:,
+            recipient_id: communication.user_id,
+          )
+          return if snapshot.nil?
+
+          communication.update!(inbox_presentation_snapshot: snapshot)
+        end
+
         def freeze_metadata(metadata)
           return nil if metadata.nil?
 

data/app/services/command_tower/messaging/contract/mappers/communication_mapper.rb

@@ -21,6 +21,7 @@ module CommandTower
               title: communication.title,
               body: communication.body,
               metadata: freeze_metadata(communication.metadata),
+              inbox_presentation_snapshot: freeze_snapshot(communication.inbox_presentation_snapshot),
               created_at: communication.created_at,
               destination_plan: DestinationPlanMapper.to_result(communication.destination_plan),
               inbox_item: InboxItemMapper.to_result(communication.inbox_item),
@@ -42,6 +43,12 @@ module CommandTower
             metadata.to_h.transform_keys(&:to_s).freeze
           end
 
+          def freeze_snapshot(snapshot)
+            return nil unless snapshot.is_a?(Hash)
+
+            snapshot.deep_stringify_keys.freeze
+          end
+
           def assert_no_active_record!(value)
             if value.is_a?(ActiveRecord::Base)
               raise Contract::InvariantError, "ActiveRecord must not leak through contract results"

data/app/services/command_tower/messaging/contract/results/communication_result.rb

@@ -11,6 +11,7 @@ module CommandTower
           :title,
           :body,
           :metadata,
+          :inbox_presentation_snapshot,
           :created_at,
           :destination_plan,
           :inbox_item,

data/app/services/command_tower/messaging/inbox/conversation_result.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Inbox
+      ConversationResult = Data.define(
+        :scope,
+        :subject,
+        :message_count,
+        :unread_count,
+        :inbox_item_ids,
+        :message_ids,
+        :window,
+      ) do
+        def self.build(scope:, subject:, message_count:, unread_count:, inbox_item_ids:, message_ids: nil, window: nil)
+          ids = Array(inbox_item_ids).map { |value| Integer(value) }.freeze
+          rendered = message_ids.nil? ? ids : Array(message_ids).map { |value| Integer(value) }.freeze
+          new(
+            scope: scope.to_s,
+            subject: subject.to_s,
+            message_count: Integer(message_count),
+            unread_count: Integer(unread_count),
+            inbox_item_ids: ids,
+            message_ids: rendered,
+            window: window&.freeze,
+          ).freeze
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/inbox/entry_result.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Inbox
+      EntryResult = Data.define(
+        :kind,
+        :id,
+        :title,
+        :preview,
+        :activity_at,
+        :created_at,
+        :message_count,
+        :unread_count,
+        :read,
+        :inbox_item_ids,
+      ) do
+        def self.build(kind:, id:, title:, preview:, activity_at:, message_count:, unread_count:, inbox_item_ids:)
+          kind = kind.to_s
+          new(
+            kind:,
+            id: kind == "conversation" ? id.to_s : Integer(id),
+            title: title.to_s,
+            preview: preview&.to_s,
+            activity_at:,
+            created_at: activity_at,
+            message_count: Integer(message_count),
+            unread_count: Integer(unread_count),
+            read: Integer(unread_count).zero?,
+            inbox_item_ids: Array(inbox_item_ids).map { |value| Integer(value) }.freeze,
+          ).freeze
+        end
+      end
+    end
+  end
+end