command_tower 0.16.0 → 0.17.0

data/app/workflows/command_tower/workflows/client_compatibility/evaluate_workflow.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Workflows
+    module ClientCompatibility
+      # Orchestrates one HTTP request's client-version-compatibility check.
+      # Maps the pure `Services::ClientCompatibility::Evaluate` projection to
+      # a `WorkflowResult`, and is the only layer (along with the boundary)
+      # allowed to place recommendation metadata onto `CommandTower::Current`
+      # — `Evaluate` itself never touches `Current` (authority §10, §13).
+      class EvaluateWorkflow < CommandTower::Workflows::ApplicationWorkflow
+        retry_strategy :none
+
+        APP_VERSION_HEADER = "X-App-Version"
+        PLATFORM_HEADER = "X-Client-Platform"
+
+        def call(request:, controller_class:, action_name:)
+          decision = CommandTower::Services::ClientCompatibility::Evaluate.call(
+            app_version_header: request.headers[APP_VERSION_HEADER],
+            platform_header: request.headers[PLATFORM_HEADER],
+            controller_class: controller_class,
+            action_name: action_name
+          )
+
+          mode = CommandTower.config.registry.client_compatibility.mode
+          enforced = mode == :enforce
+          blocked = enforced && decision.incompatible?
+
+          log_decision(decision, mode:, enforced:, blocked:)
+          stash_recommendation!(decision)
+
+          if blocked
+            return failure(
+              errors: [CommandTower::Errors::ClientUpdateRequiredError.new(details: details_for(decision))],
+              http_status: :upgrade_required
+            )
+          end
+
+          success(payload: { decision: decision })
+        end
+
+        private
+
+        def stash_recommendation!(decision)
+          return unless decision.recommendation_projection
+
+          CommandTower::Current.client_compatibility_recommendation = decision.recommendation_projection
+        end
+
+        def details_for(decision)
+          {
+            platform: decision.platform&.to_s,
+            scope: decision.scope&.to_s,
+            currentVersion: decision.current_version,
+            minimumVersion: decision.effective_minimum,
+            recovery: decision.recovery&.to_s,
+            updateUrl: decision.update_url
+          }.compact
+        end
+
+        # Structured (non-audit) decision log via the semantic `command_tower.log.*`
+        # event contract (authority §20). Workflows must not write lifecycle
+        # observation directly to `Rails.logger` — `publish_event` routes
+        # through `CommandTower::Logging::Subscriber` like every other
+        # semantic log line.
+        def log_decision(decision, mode:, enforced:, blocked:)
+          payload = {
+            message: "client_compatibility.evaluated",
+            mode: mode,
+            enforced: enforced,
+            platform: decision.platform,
+            app_version: decision.current_version,
+            matched_entities: decision.matched_entity_names,
+            decision: decision.decision,
+            http_status: blocked ? 426 : nil
+          }.compact
+
+          publish_event(category: :log, name: blocked ? :warn : :info, payload:)
+        end
+      end
+    end
+  end
+end

data/app/workflows/command_tower/workflows/client_compatibility/recommendation_meta.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Workflows
+    module ClientCompatibility
+      # Shared sequence fragment: reads the recommendation projection that
+      # `EvaluateWorkflow` stashed on `Current` (never written by `Evaluate`
+      # itself) and shapes it into `WorkflowResult.meta`. Included only by
+      # Login and Session::Show — recommended-update guidance is deliberately
+      # not attached to every success envelope (authority §13).
+      module RecommendationMeta
+        extend ActiveSupport::Concern
+
+        private
+
+        def client_compatibility_meta
+          recommendation = CommandTower::Current.client_compatibility_recommendation
+          return {} if recommendation.blank?
+
+          { clientCompatibility: recommendation }
+        end
+      end
+    end
+  end
+end

data/docs/api_reference.md

@@ -338,8 +338,8 @@ Pagination for list: query `limit` (default **50**, max **100**), `offset` (defa
 | Method | Path | Notes |
 |--------|------|--------|
 | `GET` | `/me/inbox` | List — `data` array of items; pagination meta |
-| `GET` | `/me/inbox/:id` | Detail (+ `body`, `metadata`, `notificationTypeKey`) |
-| `POST` | `/me/inbox/:id/open` | Detail |
+| `GET` | `/me/inbox/:id` | Detail (+ `body`, `metadata`, `notificationTypeKey`, `content`) |
+| `POST` | `/me/inbox/:id/open` | Detail (+ `content`) |
 | `PATCH` | `/me/inbox/:id/archive` | Item |
 | `DELETE` | `/me/inbox/:id` | `data: null` |
 | `GET` | `/me/inbox/unread-count` | `{ count }` |
@@ -349,6 +349,17 @@ Pagination for list: query `limit` (default **50**, max **100**), `offset` (defa
 | `POST` | `/me/inbox/bulk/restore` | same |
 | `POST` | `/me/inbox/bulk/delete` | same |
 
+**`content` (detail only, response-only — `inbox_document_v1`):** rendered at read from the item's `Communication`, never persisted; absent from list items. Shape: `{ schema: "inbox_document_v1", blocks: [...] }`. Allowlisted block types:
+
+| Block | Fields | Notes |
+|-------|--------|-------|
+| `paragraph` | `text` (string) | |
+| `cta` | `label` (string), `href` (string) | `href` must be `http(s)` or a custom scheme (e.g. `pickem://...`); `javascript:`/`data:`/`vbscript:`, schemeless, blank, and unparsable hrefs are rejected — the `cta` block is simply omitted, never an error |
+
+Generic (default) rendering: one `paragraph` block from `communication.body` (omitted if blank — `blocks` can legitimately be `[]`), plus one `cta` block if `metadata.deep_link` is a safe href (label from `metadata.cta_label`, default `"Open"`).
+
+Hosts may override the document per `notificationTypeKey` with an `inbox_document.json.erb` view at `app/views/command_tower/messaging/rendering/<notification_type_key>/inbox_document.json.erb` (same lookup convention as [`messaging_integration_guide.md`](messaging_integration_guide.md#rendering-template-overrides)). Any failure resolving or rendering that template (missing file, malformed JSON, wrong `schema`/`blocks` shape, or a raising template) fails open to the generic document — the Inbox read path never 500s on a bad type template. A valid envelope with one invalid/unknown block strips only that block; if stripping empties `blocks`, the generic document is used instead.
+
 **List item fields:** `id`, `title`, `status`, `read`, `viewedAt`, `createdAt`, `updatedAt`.
 
 **Errors:** `401` / `403` / `422`; show/open may return `404` `not_found`.

data/docs/extending.md

@@ -19,6 +19,7 @@ Layer map: [architecture.md](architecture.md). Install/configure/migrate/doctor:
 | Model reopen | Product associations / behavior |
 | Initializers | Configuration, including `config.registry.audit.event`, `config.registry.admin_workspace.tool`, and `config.registry.principal_capabilities.capability` |
 | Notification catalogs / channel policy | Host-owned messaging customization |
+| `app/views/command_tower/messaging/rendering/**` | Host override of generic and/or per-`notification_type_key` rendered Email/SMS/Pushover/Push templates — see [messaging_integration_guide.md](messaging_integration_guide.md#rendering-template-overrides) |
 
 ## Internal platform — do not extend
 
@@ -28,7 +29,7 @@ Layer map: [architecture.md](architecture.md). Install/configure/migrate/doctor:
 | ServiceBase | Shared service framework |
 | Serializers | Platform response shaping |
 | Deserializers | Platform request trust boundary |
-| Messaging execution pipeline | Handoff / execution / accept internals |
+| Messaging execution pipeline | Handoff / execution / accept internals, including `Messaging::Rendering::ChannelRenderer` / `TemplateResolver` Ruby classes — hosts customize rendering by dropping ERB views (above), never by reopening or calling these classes |
 | RequestContext | Framework request context |
 | JWT primitives | Token issue / validate plumbing |
 | Internal framework plumbing | Envelope renderer, workflow base mechanics, etc. |

data/docs/host_integration_guide.md

@@ -222,6 +222,41 @@ CommandTower::Testing.install!
 
 Details: [Testing](testing.md). Prefer `spec/requests/` patterns in the gem as HTTP contract proof.
 
+## Step 11 — Client version compatibility (optional)
+
+CommandTower can gate or warn on stale client app versions per platform, ahead of every request (before authn/authz). It is entirely opt-in: an untouched registry is a no-op, and the shipped CommandTower-owned catalog is empty by design.
+
+```ruby
+CommandTower.configure do |c|
+  c.registry.client_compatibility.mode = :observe # or :enforce; default observe
+
+  c.registry.client_compatibility.platform :web do |platform|
+    platform.minimum = "1.0.0"      # required; MAJOR.MINOR.PATCH[.prerelease]
+    platform.recommended = "1.2.0"  # optional; non-blocking upgrade guidance
+    # platform.update_url is forbidden on :web (web recovery is "reload", not a store)
+  end
+
+  c.registry.client_compatibility.platform :ios do |platform|
+    platform.minimum = "2.0.0"
+    platform.update_url = "https://apps.apple.com/app/id..."
+  end
+
+  # Optional: a capability-scoped floor stricter than the platform-global minimum,
+  # bound to an existing RBAC entity (see Step 4).
+  c.registry.client_compatibility.entity :some_host_entity do |entity|
+    entity.minimum.ios = "2.1.0"
+  end
+end
+```
+
+- Canonical platforms are `web` | `ios` | `android`. Configure only what your app ships — `android` unconfigured never fails boot on its own.
+- Zero configured platforms while otherwise opted in (non-default `mode`, any `entity`/`client_contract`/`bind`) fails boot fast; a completely untouched registry does not.
+- `X-App-Version` / `X-Client-Platform` request headers drive evaluation — never User-Agent, never an allowlist.
+- Every controller runs the check via `before_action :evaluate_client_compatibility!` on `CommandTower::ApplicationController`. Exempt a controller with `skip_before_action :evaluate_client_compatibility!`.
+- Process-level ENV overlays may only **raise** an already-configured platform's minimum, never lower it or configure a platform the host didn't enable: `COMMAND_TOWER_CLIENT_COMPATIBILITY_MODE=observe|enforce`, `COMMAND_TOWER_CLIENT_COMPATIBILITY_MINIMUM_WEB|IOS|ANDROID=<version>`.
+- In `:observe` mode nothing is ever blocked — decisions are logged only. In `:enforce` mode, an incompatible or unparseable identity renders HTTP `426` with a `client_update_required` error envelope.
+- Recommended-update guidance (when a client is compatible but below `recommended`) is surfaced only in `meta.clientCompatibility` on login and session-show responses — never on every response.
+
 ## Done when
 
 - Doctor passes for secrets/migrations

data/docs/messaging_integration_guide.md

@@ -59,6 +59,44 @@ CommandTower::Services::Messaging::Communications::Produce.call(
 
 Admin announcements HTTP is a product path over ProduceMany (async/sync, audience selection). Contract: [API reference — Admin messaging](api_reference.md#admin-messaging).
 
+## Rendering template overrides
+
+`ChannelRenderer` resolves each rendered destination (email HTML/text, SMS, Pushover, push) by `notification_type_key` first, falling back to a generic template — and always prefers a **host** view over CommandTower's own engine default for either. Hosts customize by dropping ERB files at this path in their own `app/views/`; they never call `ChannelRenderer` or its internal `TemplateResolver` collaborator directly.
+
+```text
+app/views/command_tower/messaging/rendering/
+  email.html.erb            # optional host override of the generic chrome
+  email.text.erb
+  sms.text.erb
+  push.text.erb
+  pushover.text.erb
+  <notification_type_key>/
+    email.html.erb          # optional type-specific override (only if the key matches [a-z0-9_]+)
+    email.text.erb
+    sms.text.erb
+    push.text.erb
+    pushover.text.erb
+```
+
+Notes:
+
+- `<notification_type_key>` directories only resolve when the key matches `/\A[a-z0-9_]+\z/`. Keys with dots (e.g. legacy `"example.type"`-style keys) or other characters always fall back to generic — they never attempt a type directory, even if one happens to exist on disk.
+- Each rendered destination resolves independently — a type directory can override just `email.html.erb` while every other destination (email text, SMS, Pushover, push) still renders from the generic templates.
+- Generic templates receive the same four locals as before (`title`, `body`, `deep_link`, `h` — an HTML-escaping helper). Type-specific templates additionally receive `metadata` (the communication's metadata Hash) and `notification_type_key`.
+- A missing or failing template (generic or type-specific) surfaces the same way it always has: `RenderError` with code `"render_failed"`.
+
+### Inbox document override (`inbox_document.json.erb`)
+
+The Me Inbox detail `content` field (`inbox_document_v1`, see [api_reference.md](api_reference.md#me-inbox)) is built by a separate collaborator, `InboxDocumentRenderer`, using the **same** type-directory convention and sanitized-key rule as above, resolved through `TemplateResolver.render_type_template`:
+
+```text
+app/views/command_tower/messaging/rendering/
+  <notification_type_key>/
+    inbox_document.json.erb   # optional type-specific inbox content override
+```
+
+This override has **no generic ERB fallback file** — the generic Inbox document is built in pure Ruby from `communication.body`/`metadata`, not from a template. Because of that, the fail-open contract here is stricter than `ChannelRenderer`'s: a missing type template, malformed JSON, an envelope with the wrong `schema` or a non-Array `blocks`, or a template that raises mid-render all fall back silently to the generic document — the Inbox read path never surfaces a `RenderError` and never 500s. A valid envelope with one invalid/unknown block strips only that block, keeping the rest; if stripping empties `blocks`, the generic document is used instead.
+
 ## Me Inbox HTTP (summary)
 
 | Concern | Contract |

data/docs/upgrades/0.17.0.md

@@ -0,0 +1,33 @@
+# Upgrade: CommandTower 0.17.0
+
+**From:** `0.16.0`  
+**To:** `0.17.0`
+
+Minor release: client-version-compatibility gating, Rich Messaging Inbox content documents, and shared email theming. No new migration.
+
+## Host-visible changes
+
+| Change | Host impact |
+|--------|-------------|
+| `config.registry.client_compatibility` | Optional per-platform (`web`/`ios`/`android`) minimum/recommended version gating, evaluated on every request ahead of authn/authz via `before_action :evaluate_client_compatibility!`. Untouched registry is a no-op. |
+| `:observe` / `:enforce` modes | `:observe` (default) only logs; `:enforce` renders `426` `client_update_required` for incompatible/unparseable client identity |
+| `meta.clientCompatibility` | Non-blocking upgrade guidance surfaced only on login and session-show responses when a compatible client is below `recommended` |
+| `X-App-Version` / `X-Client-Platform` headers | New request contract driving evaluation — never User-Agent |
+| `GET`/`POST open` `/me/inbox/:id` `content` field | New `inbox_document_v1` field rendered at read time from the `Communication` (never persisted); generic Ruby-built `paragraph`/`cta` blocks, or a host `inbox_document.json.erb` override per `notification_type_key` |
+| `Messaging::Rendering::ChannelRenderer` template resolution | Now resolves per-destination host ERB overrides (`app/views/command_tower/messaging/rendering/**`) before falling back to engine defaults, instead of a single fixed `TEMPLATE_DIR` |
+| `config.email_theme` | New composer for semantic email theme tokens; verification and password-reset mailer views now render through `CommandTower::EmailTheme::Resolver` instead of hardcoded hex colors |
+| `config.registry.inbox_presentations` | New host-owned-only registry (no CommandTower-seeded presentations) supporting Rich Messaging Inbox host customization |
+
+## Host actions
+
+1. Bump gem to `0.17.0` (or `>= 0.17.0`).
+2. No new migration — **`bundle exec rails command_tower:install:migrations` is not required** for this release.
+3. Optional: configure `config.registry.client_compatibility` per platform if you want version gating; leaving it untouched is a no-op.
+4. Optional: customize email theme via `config.email_theme`, or override rendered Messaging templates / `inbox_document.json.erb` per `notification_type_key` under `app/views/command_tower/messaging/rendering/`.
+5. If your host renders `/me/inbox/:id`, expect the new `content` field in detail responses (list items are unaffected).
+
+## Not in this release
+
+- CommandTower frontend client-compatibility banners / upgrade prompts
+- CommandTower-owned Inbox presentation catalog entries (registry remains host-owned-only)
+- `android` platform enforcement examples beyond the documented ENV overlay contract

data/docs/upgrades/README.md

@@ -4,6 +4,7 @@ Host-facing upgrade / change summaries for CommandTower releases.
 
 | Version | Summary |
 |---------|---------|
+| [0.17.0](0.17.0.md) | Client-version-compatibility gating (`observe`/`enforce`); Rich Messaging Inbox `content` documents; host-overridable rendering templates; shared email theming |
 | [0.16.0](0.16.0.md) | Me experience-states (`GET`/`POST complete`); `host_key`; `user_experience_states` migration; `me_experience_states` RBAC |
 | [0.15.0](0.15.0.md) | Me `POST /me/push/test` → Produce (`push_delivery_test`); configurable Expo self-test rate limit composers; `me_push#test` |
 | [0.14.0](0.14.0.md) | Expo push Messaging channel (`config.messaging.expo`) + `/api/me/push*` registration HTTP; `me_push` RBAC |

data/lib/command_tower/client_compatibility/version.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module ClientCompatibility
+    # Strict client-version identity parsing (authority §12).
+    #
+    # `Gem::Version` alone is too permissive: it accepts partial shapes such as
+    # "1" or "1.2". The authority requires the full MAJOR.MINOR.PATCH shape,
+    # with an optional dot-delimited prerelease tail (e.g. "1.2.3.beta.1").
+    # Build metadata (e.g. "+build"), hyphenated prerelease tokens, and any
+    # other malformed shape are rejected as invalid identity — never coerced
+    # into a "valid but low" version.
+    module Version
+      FORMAT = /\A[vV]?\d+\.\d+\.\d+(\.[A-Za-z0-9]+)*\z/
+
+      module_function
+
+      # Returns a normalized (leading "v"/"V" stripped) version string, or nil
+      # when the raw value does not conform to the strict MAJOR.MINOR.PATCH
+      # (+ optional prerelease) shape.
+      def normalize(raw)
+        token = raw.to_s.strip
+        return nil if token.empty?
+        return nil unless token.match?(FORMAT)
+
+        token.sub(/\A[vV]/, "")
+      end
+
+      def valid?(raw)
+        !normalize(raw).nil?
+      end
+
+      # Returns a Gem::Version for a strictly-valid raw value, or nil otherwise.
+      # Callers that need a hard failure on invalid input should check
+      # `valid?`/`normalize` explicitly rather than relying on Gem::Version's
+      # own (looser) parsing.
+      def parse(raw)
+        normalized = normalize(raw)
+        return nil if normalized.nil?
+
+        Gem::Version.new(normalized)
+      end
+    end
+  end
+end

data/lib/command_tower/client_compatibility.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module ClientCompatibility
+    class Error < CommandTower::Error; end
+
+    class HostOverrideError < Error; end
+    class DuplicateContractError < Error; end
+    class DuplicateEntityRequirementError < Error; end
+    class DuplicateBindingError < Error; end
+    class UnknownClientContractError < Error; end
+    class UnboundClientContractError < Error; end
+    class UnknownEntityError < Error; end
+    class InvalidPlatformError < Error; end
+    class InvalidContractIdError < Error; end
+    class InvalidEntityNameError < Error; end
+    class InvalidVersionError < Error; end
+    class InvalidModeError < Error; end
+    class ConflictingRequirementError < Error; end
+    class NoConfiguredPlatformsError < Error; end
+    class FrozenRegistryError < Error; end
+  end
+end

data/lib/command_tower/configuration/config.rb

@@ -10,6 +10,7 @@ require "command_tower/configuration/authorization/config"
 require "command_tower/configuration/base"
 require "command_tower/configuration/credentials/config"
 require "command_tower/configuration/email/config"
+require "command_tower/configuration/email_theme/config"
 require "command_tower/configuration/identity/config"
 require "command_tower/configuration/impersonation/config"
 require "command_tower/configuration/jwt/config"
@@ -49,6 +50,11 @@ module CommandTower
         allowed: Configuration::Email::Config,
         default: Configuration::Email::Config.new
 
+      add_composer :email_theme,
+        desc: "Semantic email theme tokens shared by Messaging and (later) auth mail templates",
+        allowed: Configuration::EmailTheme::Config,
+        default: Configuration::EmailTheme::Config.new
+
       add_composer :credentials,
         desc: "Deployment provider credentials (typed per provider under config.credentials.<provider>). Consumed by Credential Resolution. Not provider behavior configuration.",
         allowed: Configuration::Credentials::Config,

data/lib/command_tower/configuration/email_theme/config.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "class_composer"
+
+module CommandTower
+  module Configuration
+    module EmailTheme
+      # Semantic email theme tokens shared by Messaging email templates and,
+      # later, CT-owned auth mail templates. CT-owned, gem-level contract —
+      # see Rich Messaging Strategy §12 (email theme sequence, step A).
+      #
+      # Deliberately holds only visual/color tokens. Product identity
+      # (name/URL) already exists on Configuration::Application::Config and
+      # is composed in by CommandTower::EmailTheme::Resolver, not duplicated
+      # here. Defaults are the current unbranded hex values already
+      # hardcoded in command_tower's generic email.html.erb and Pick'em's
+      # incomplete_wager/email.html.erb, so introducing this contract is a
+      # no-op until a template is switched to consume it.
+      class Config < ::CommandTower::Configuration::Base
+        include ClassComposer::Generator
+
+        add_composer :canvas_background,
+          allowed: String,
+          default: "#f4f5f7",
+          desc: "Outer email canvas background color"
+
+        add_composer :surface_background,
+          allowed: String,
+          default: "#ffffff",
+          desc: "Card/surface background color"
+
+        add_composer :surface_border,
+          allowed: String,
+          default: "#e2e8f0",
+          desc: "Card/surface border color"
+
+        add_composer :primary_text,
+          allowed: String,
+          default: "#1a202c",
+          desc: "Headline/primary text color"
+
+        add_composer :body_text,
+          allowed: String,
+          default: "#4a5568",
+          desc: "Body copy text color"
+
+        add_composer :muted_text,
+          allowed: String,
+          default: "#718096",
+          desc: "De-emphasized/secondary text color"
+
+        add_composer :accent,
+          allowed: String,
+          default: "#2b6cb0",
+          desc: "Single flat accent color (collapses any gradient to one value)"
+
+        add_composer :text_on_accent,
+          allowed: String,
+          default: "#ffffff",
+          desc: "Text/icon color rendered on top of the accent color"
+
+        add_composer :primary_action,
+          allowed: String,
+          default: "#2b6cb0",
+          desc: "Link/button primary-action color"
+      end
+    end
+  end
+end

data/lib/command_tower/configuration/registry/client_compatibility/binding_definition.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "class_composer"
+
+module CommandTower
+  module Configuration
+    module Registry
+      module ClientCompatibility
+        # Host-owned per-platform host-app version bound to a named client
+        # contract. Authority §7.
+        class BindingDefinition
+          include ClassComposer::Generator
+
+          add_composer :web, desc: "Bound host-app version for web", allowed: [String, NilClass], default: nil
+          add_composer :ios, desc: "Bound host-app version for ios", allowed: [String, NilClass], default: nil
+          add_composer :android, desc: "Bound host-app version for android", allowed: [String, NilClass], default: nil
+
+          def for_platform(platform)
+            public_send(platform)
+          end
+
+          def validate!(contract_id:)
+            %i[web ios android].each do |platform|
+              value = public_send(platform)
+              next if value.blank?
+
+              normalized = CommandTower::ClientCompatibility::Version.normalize(value)
+              if normalized.nil?
+                raise CommandTower::ClientCompatibility::InvalidVersionError,
+                  "binding for client contract #{contract_id} has invalid #{platform} #{value.inspect}"
+              end
+
+              public_send("#{platform}=", normalized)
+            end
+
+            self
+          end
+        end
+      end
+    end
+  end
+end