command_tower 0.15.0 → 0.17.0

data/docs/host_integration_guide.md

@@ -32,10 +32,11 @@ In the host initializer, set at least:
 - `config.jwt.hmac_secret`
 - `config.signup_session.jwt_secret` (or `SIGNUP_SESSION_JWT_SECRET`)
 - `config.password_recovery_session.jwt_secret` (or `PASSWORD_RECOVERY_SESSION_JWT_SECRET`)
+- `config.application.host_key` — server-bound host/product identity for CT-generic user-scoped state (for example experience states). Not client-supplied. Blank values cause Me experience-state routes to return **503** `experience_states_host_unconfigured`.
 
 Re-run `bin/rails command_tower:doctor`. Details: [Initializing — Configuration](initializing.md#configuration).
 
-Dummy-host reference: [`rails_app/config/initializers/command_tower.rb`](../rails_app/config/initializers/command_tower.rb).
+Dummy-host reference: [`rails_app/config/initializers/command_tower.rb`](../rails_app/config/initializers/command_tower.rb) (sets `host_key` to `"command_tower"`).
 
 ### Email / SMTP
 
@@ -221,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/initializing.md

@@ -107,6 +107,7 @@ Required for production-ready hosts:
 - `config.jwt.hmac_secret` — typically `SECRET_KEY_BASE` / `Rails.application.secret_key_base`
 - `config.signup_session.jwt_secret` — or `SIGNUP_SESSION_JWT_SECRET`
 - `config.password_recovery_session.jwt_secret` — or `PASSWORD_RECOVERY_SESSION_JWT_SECRET`
+- `config.application.host_key` — server-bound host/product identity for CT-generic user-scoped state (experience states). Not client-supplied. Blank → Me experience-state routes return **503**.
 
 Optional / feature-gated:
 

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.16.0.md

@@ -0,0 +1,30 @@
+# Upgrade: CommandTower 0.16.0
+
+**From:** `0.15.0`  
+**To:** `0.16.0`
+
+Minor release: generic Me experience-state persistence and HTTP (completion facts only). New migration.
+
+## Host-visible changes
+
+| Change | Host impact |
+|--------|-------------|
+| Table `user_experience_states` | Durable completion rows keyed by `user + host_key + experience_key + scope_type + scope_identifier + version` |
+| `config.application.host_key` | **Required** non-blank String for Me experience-states. Server-bound; never client-supplied. Blank → **503** `experience_states_host_unconfigured` |
+| `GET /api/me/experience-states` | Authenticated list of **completed** facts for the current user on this host only |
+| `POST /api/me/experience-states/complete` | Idempotent complete; audit `experience_state_completed` **only on first durable create** |
+| RBAC `me_experience_states` | New entity (`index`, `complete`). Hosts must **explicitly grant** (not auto-added to a generic Admin role) |
+| Audit | Configurable event `experience_state_completed` with opaque `host_context` |
+
+## Host actions
+
+1. Bump gem to `0.16.0` (or `>= 0.16.0`).
+2. Set `config.application.host_key` (e.g. Pick’em `"pickem"`; CT rails_app `"command_tower"`).
+3. Copy engine migrations and migrate: `bundle exec rails command_tower:install:migrations` then `db:migrate`.
+4. Grant RBAC entity `me_experience_states` to the roles/groups that should use Me experience-states (typically `member`).
+
+## Not in this release
+
+- CommandTower frontend experience-states capability / hydrate hooks
+- Host Welcome product composition
+- Push silent-sync / Welcome notification step

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,8 @@ 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 |
 | [0.13.1](0.13.1.md) | Canonical `Intervention::Severity` constants (`blocking`, `warning`, `informational`) |

data/lib/command_tower/authorization/default.yml

@@ -76,6 +76,11 @@ entities:
       - update
       - destroy
       - test
+  - name: me_experience_states
+    controller: CommandTower::Me::ExperienceStatesController
+    only:
+      - index
+      - complete
   - name: me_audit_events
     controller: CommandTower::Me::AuditEventsController
     only:

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/application/config.rb

@@ -14,6 +14,11 @@ module CommandTower
           desc: "The default name of the application",
           default_shown: "# Auto Populates to the name of the application"
 
+        add_composer :host_key,
+          allowed: String,
+          default: "",
+          desc: "Server-bound host/product identity for CT-generic user-scoped state. Not client-supplied."
+
         add_composer :communication_name,
           allowed: String,
           dynamic_default: :app_name,

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/audit/config.rb

@@ -265,6 +265,18 @@ module CommandTower
               subject_type: "User",
               affected_user_required: true,
               global_visible_in_host_scope: true
+            },
+            experience_state_completed: {
+              label: "Experience state completed",
+              tags: %w[experience account],
+              enabled: true,
+              enablement_configurable: true,
+              user_history: false,
+              sensitive_fields: [],
+              allowed_changes: [],
+              retention: :permanent,
+              subject_required: false,
+              affected_user_required: true
             }
           }.freeze
 

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