command_tower 0.11.1 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d495e295241fa7ac4f9179acc5fd2d4c47fcb8a0603dccdf5353ac08e7c98b28
-  data.tar.gz: 9d56364ffd4a79ad9bcabe07e2713a2613b2d43112039bc5f31db855f3baad2d
+  metadata.gz: 478979c1e8cabe23c8a2b666d7d42ec610abef048a302f4e8e7a5b5b7d9d74b0
+  data.tar.gz: 82a5c9c35c78c0a22f1cddf038b203fd0d32433a78be139e386024971189fa05
 SHA512:
-  metadata.gz: f605fe2a8117b8e5b6af32dc7c65df55c9400a33a5d50220f5a0c992efd74f28545a8fbfe8c293982f062f398dcc3b86aa552de12d1ec87f733e5a2d6435169e
-  data.tar.gz: 85072dd065a8589a239166286a2261a331a7cd9c59e0b0c7eb870e5bc60dcfdeb4d32df84671015a93d2edcd3a93592e7647210cf5f553c4a47a346abb214bdb
+  metadata.gz: 22fe0f30d9fdd950b976dfad3cb8818bd51eb7cb4877a550fa1c58de69092e8e99ca940dc0c244c9c0343fb8d875b6ea2730f929ac722da7bcc980dabc45d1f0
+  data.tar.gz: b5db99a8faa23f2a9d872cae17354f4f005525e5105db924b338778912164fa52cab8c4456cc8c9ea0f6baab4a9a72de44243d713f0d4fa20abadd032294ecde

data/app/deserializers/command_tower/deserializers/intervention/envelope_deserializer.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Deserializers
+    module Intervention
+      # Parses a canonical intervention envelope from untrusted params/JSON.
+      class EnvelopeDeserializer < CommandTower::Deserializers::ApplicationDeserializer
+        Input = Data.define(:action, :allowed, :blockers)
+
+        def call(params)
+          source = normalize_source(params)
+          action = required_text(source[:action] || source["action"], field: "action")
+          return action if deserializer_result?(action)
+
+          allowed_raw = source[:allowed].nil? ? source["allowed"] : source[:allowed]
+          allowed = allowed_raw == true || allowed_raw.to_s == "true"
+
+          blockers_raw = source[:blockers] || source["blockers"] || []
+          unless blockers_raw.is_a?(Array)
+            return failure(errors: [{ field: "blockers", code: "invalid_type", message: "must be an array" }])
+          end
+
+          blockers = []
+          blockers_raw.each_with_index do |row, index|
+            parsed = parse_blocker(row, index)
+            return parsed if deserializer_result?(parsed)
+
+            blockers << parsed
+          end
+
+          success(Input.new(action: action, allowed: allowed, blockers: blockers))
+        end
+
+        private
+
+        def normalize_source(params)
+          return params.to_unsafe_h if params.respond_to?(:to_unsafe_h)
+          return params.to_h if params.respond_to?(:to_h)
+
+          params.is_a?(Hash) ? params : {}
+        end
+
+        def required_text(raw, field:)
+          value = raw.is_a?(String) ? raw.strip : raw.to_s.strip
+          if value.empty?
+            return failure(errors: [{ field: field, code: "missing_required_fields", message: "is required" }])
+          end
+
+          value
+        end
+
+        def parse_blocker(row, index)
+          unless row.is_a?(Hash)
+            return failure(
+              errors: [{ field: "blockers[#{index}]", code: "invalid_type", message: "must be an object" }]
+            )
+          end
+
+          code = required_text(row[:code] || row["code"], field: "blockers[#{index}].code")
+          return code if deserializer_result?(code)
+
+          action = required_text(row[:action] || row["action"], field: "blockers[#{index}].action")
+          return action if deserializer_result?(action)
+
+          title = required_text(row[:title] || row["title"], field: "blockers[#{index}].title")
+          return title if deserializer_result?(title)
+
+          message = required_text(row[:message] || row["message"], field: "blockers[#{index}].message")
+          return message if deserializer_result?(message)
+
+          blocker = {
+            code: code,
+            action: action,
+            title: title,
+            message: message
+          }
+
+          severity = row[:severity] || row["severity"]
+          blocker[:severity] = severity.to_s if severity.present?
+
+          remediation_raw = row[:remediation] || row["remediation"]
+          if remediation_raw.present?
+            remediation = parse_remediation(remediation_raw, index)
+            return remediation if deserializer_result?(remediation)
+
+            blocker[:remediation] = remediation
+          end
+
+          blocker
+        end
+
+        def parse_remediation(row, index)
+          unless row.is_a?(Hash)
+            return failure(
+              errors: [
+                { field: "blockers[#{index}].remediation", code: "invalid_type", message: "must be an object" }
+              ]
+            )
+          end
+
+          kind = required_text(row[:kind] || row["kind"], field: "blockers[#{index}].remediation.kind")
+          return kind if deserializer_result?(kind)
+
+          action = required_text(row[:action] || row["action"], field: "blockers[#{index}].remediation.action")
+          return action if deserializer_result?(action)
+
+          remediation = { kind: kind, action: action }
+          label = row[:label] || row["label"]
+          remediation[:label] = label.to_s if label.present?
+          remediation
+        end
+      end
+    end
+  end
+end

data/app/serializers/command_tower/serializers/intervention/blocker_serializer.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Serializers
+    module Intervention
+      # One presentation-independent blocker fact. No presentation mode / routes / host policy.
+      class BlockerSerializer < CommandTower::Serializers::ApplicationSerializer
+        def self.serialize(code:, action:, title:, message:, remediation: nil, severity: nil)
+          payload = {
+            code: code.to_s,
+            action: action.to_s,
+            title: title.to_s,
+            message: message.to_s
+          }
+          payload[:severity] = severity.to_s if severity.present?
+          if remediation
+            payload[:remediation] = RemediationSerializer.serialize(**remediation)
+          end
+          payload
+        end
+      end
+    end
+  end
+end

data/app/serializers/command_tower/serializers/intervention/envelope_serializer.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Serializers
+    module Intervention
+      # Action-scoped intervention envelope for GET projections and mutation errors.
+      # `blockers` ordered; primary is first. No presentation-mode fields.
+      # Host/CT FE owns presentation modes (callout, intercept, sheet, blocking_region).
+      class EnvelopeSerializer < CommandTower::Serializers::ApplicationSerializer
+        def self.serialize(action:, allowed:, blockers: [])
+          {
+            action: action.to_s,
+            allowed: allowed == true,
+            blockers: map_serialize(blockers) { |blocker| BlockerSerializer.serialize(**blocker) }
+          }
+        end
+
+        def self.serialize_many(envelopes)
+          map_serialize(envelopes) { |envelope| serialize(**envelope) }
+        end
+      end
+    end
+  end
+end

data/app/serializers/command_tower/serializers/intervention/remediation_serializer.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Serializers
+    module Intervention
+      # Canonical remediation facts (presentation-independent). Host maps `action` to routes.
+      class RemediationSerializer < CommandTower::Serializers::ApplicationSerializer
+        def self.serialize(kind:, action:, label: nil)
+          payload = {
+            kind: kind.to_s,
+            action: action.to_s
+          }
+          payload[:label] = label.to_s if label.present?
+          payload
+        end
+      end
+    end
+  end
+end

data/docs/admin_workspace.md

@@ -46,7 +46,9 @@ Hosts configure scope behavior on `CommandTower.config.admin_scope` (see [Resour
 
 ## Resource scoping
 
-Optional **host-defined resource scoping** narrows Admin tool data (Users, Audit, …) after RBAC. CommandTower remains **domain-blind** — it does not know League, Season, or tenant semantics.
+Optional **host-defined resource scoping** selects a scope value before entering a tool and, for Users/Audit, narrows Admin tool data after RBAC. CommandTower remains **domain-blind** — it does not know League, Season, or tenant semantics.
+
+Every `admin_scope.register` requires **`options`**, **`validate`**, and **`availability`**. Resource-narrowing hooks (`narrow_users`, `narrow_audit`, `affected_users_in_scope`) are required for CT-owned **`users`** / **`audit`** (or whenever any narrowing hook is set). Product Admin host tools may register the three base hooks only — scope drives Workspace invocation (0/1/N), not CT SQL narrowing.
 
 ```ruby
 CommandTower.configure do |config|
@@ -64,23 +66,41 @@ CommandTower.configure do |config|
     registration.narrow_audit = ->(relation:, scope_value:, principal:, tool_id:) { relation }
     registration.affected_users_in_scope = ->(scope_value:, principal:, tool_id:) { [] }
   end
+
+  # Product Admin host tool — invocation scope only (no Users/Audit narrowing).
+  config.registry.admin_workspace.tool :example_product_admin do |tool|
+    tool.label = "Example Product Admin"
+    tool.route = "/admin/example-product"
+    tool.group = :product
+    tool.sort_order = 300
+    tool.required_entity = :host_example_entity
+    tool.scope_required = true
+    tool.scope_parameter = "resource_slug"
+    tool.scope_label = "Resource"
+  end
+
+  config.admin_scope.register(:example_product_admin) do |registration|
+    registration.options = ->(principal:) { [CommandTower::AdminScope::ScopeOption.new(value: "x", label: "X")] }
+    registration.validate = ->(value:, principal:) { value.to_s == "x" }
+    registration.availability = ->(principal:) { { enabled: true, reason: nil } }
+  end
 end
 ```
 
-| Hook | Purpose |
-|------|---------|
-| `options` | Eager scope choices for manifest (`scopeOptions`) |
-| `availability` | `{ enabled:, reason: }` — disabled tools render non-navigable in FE |
-| `validate` | Authorize requested scope value; fail closed → **403** |
-| `narrow_users` | SQL narrowing for Users list/show |
-| `narrow_audit` | SQL narrowing for host-scoped audit rows |
-| `affected_users_in_scope` | User ids for eligible **global** audit events in scoped admin views |
+| Hook | Purpose | Required |
+|------|---------|----------|
+| `options` | Eager scope choices for manifest (`scopeOptions`) | Always |
+| `availability` | `{ enabled:, reason: }` — disabled tools render non-navigable in FE | Always |
+| `validate` | Authorize requested scope value; fail closed → **403** | Always |
+| `narrow_users` | SQL narrowing for Users list/show | `users` / `audit` only |
+| `narrow_audit` | SQL narrowing for host-scoped audit rows | `users` / `audit` only |
+| `affected_users_in_scope` | User ids for eligible **global** audit events in scoped admin views | `users` / `audit` only |
 
-**HTTP disclosure policy:** missing/malformed/unauthorized scope → **403**; authorized scope + resource absent from narrowed relation (nonexistent **or** out of scope) → **404** (indistinguishable).
+**HTTP disclosure policy** (Users/Audit resource APIs): missing/malformed/unauthorized scope → **403**; authorized scope + resource absent from narrowed relation (nonexistent **or** out of scope) → **404** (indistinguishable).
 
 Unscoped tools (`scope_required: false`, default) behave exactly as before — no scope query param, no `admin_scope` registration required.
 
-Synthetic proof lives in `rails_app` (`FoundationProof::AdminScope`); Pick'em League adoption is Phase 7 only.
+Synthetic proof lives in `rails_app` (`FoundationProof::AdminScope`). Hosts own product-scoped destinations via FE `resolveScopedDestination` — CT does not interpret path params.
 
 ## Seeded CommandTower tools
 

data/docs/upgrades/0.12.0.md

@@ -0,0 +1,26 @@
+# Upgrade: CommandTower 0.12.0
+
+**From:** `0.11.1`  
+**To:** `0.12.0`
+
+Minor release: canonical action-intervention envelope ser/de, and Admin Scope registrations that do not require Users/Audit resource-narrowing for host product tools.
+
+## Host-visible changes
+
+| Change | Host impact |
+|--------|-------------|
+| Intervention envelope | `CommandTower::Serializers::Intervention::EnvelopeSerializer` / `EnvelopeDeserializer` (plus blocker/remediation serializers). Canonical `{ action, allowed, blockers[] }` with ordered blockers; **no** presentation-mode fields. Host/CT FE owns `callout` / `intercept` / `sheet` / `blocking_region`. |
+| Admin Scope hook requirements | Every `admin_scope.register` still requires `options`, `validate`, and `availability`. Resource-narrowing hooks (`narrow_users`, `narrow_audit`, `affected_users_in_scope`) are required for CT-owned **`users`** / **`audit`**, or whenever any narrowing hook is set. Host product tools may register the three base hooks only. |
+
+## Host actions
+
+1. Bump gem to `0.12.0`.
+2. **No new migration.**
+3. To emit interventions from host workflows, serialize with `EnvelopeSerializer` (and `serialize_many` for action maps). Do not invent a parallel envelope shape.
+4. Hosts with scoped product Admin tools can drop unused Users/Audit narrowing hooks from those registrations.
+
+## Not in this release
+
+- Frontend `ActionIntervention` presentation (ships in `@commandtower/frontend`)
+- Changing Users/Audit narrowing requirements
+- New HTTP routes

data/docs/upgrades/README.md

@@ -4,6 +4,7 @@ Host-facing upgrade / change summaries for CommandTower releases.
 
 | Version | Summary |
 |---------|---------|
+| [0.12.0](0.12.0.md) | Intervention envelope serializers/deserializers; product-tool admin_scope without Users/Audit narrowing |
 | [0.11.1](0.11.1.md) | Audit Event `attribute :json` (MariaDB); audit migration without `utf8mb4_0900_ai_ci` |
 | [0.11.0](0.11.0.md) | Execution context, audit ledger, Admin Workspace, principal capabilities, impersonation, Admin Users |
 | [0.10.0](0.10.0.md) | Modern Auth/Me/Messaging platform; SchemaHelper removal; host RBAC required |

data/lib/command_tower/configuration/admin_scope/tool_registration.rb

@@ -4,13 +4,15 @@ module CommandTower
   module Configuration
     module AdminScope
       class ToolRegistration
-        REQUIRED_HOOKS = %i[options validate availability narrow_users narrow_audit affected_users_in_scope].freeze
+        BASE_HOOKS = %i[options validate availability].freeze
+        RESOURCE_NARROWING_HOOKS = %i[narrow_users narrow_audit affected_users_in_scope].freeze
+        RESOURCE_SCOPED_TOOL_IDS = %w[users audit].freeze
 
         attr_accessor :options, :validate, :availability, :narrow_users, :narrow_audit,
           :affected_users_in_scope, :host_context_type
 
         def validate!(tool_id:)
-          missing = REQUIRED_HOOKS.reject { |hook| callable?(public_send(hook)) }
+          missing = required_hooks_for(tool_id).reject { |hook| callable?(public_send(hook)) }
           return self if missing.empty?
 
           raise CommandTower::AdminScope::InvalidToolRegistrationError,
@@ -19,6 +21,19 @@ module CommandTower
 
         private
 
+        def required_hooks_for(tool_id)
+          hooks = BASE_HOOKS.dup
+          normalized = tool_id.to_s
+          if RESOURCE_SCOPED_TOOL_IDS.include?(normalized) || resource_narrowing_hooks_present?
+            hooks.concat(RESOURCE_NARROWING_HOOKS)
+          end
+          hooks
+        end
+
+        def resource_narrowing_hooks_present?
+          RESOURCE_NARROWING_HOOKS.any? { |hook| !public_send(hook).nil? }
+        end
+
         def callable?(value)
           value.respond_to?(:call)
         end

data/lib/command_tower/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CommandTower
-  VERSION = "0.11.1"
+  VERSION = "0.12.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: command_tower
 version: !ruby/object:Gem::Version
-  version: 0.11.1
+  version: 0.12.0
 platform: ruby
 authors:
 - matt-taylor
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-08-22 00:00:00.000000000 Z
+date: 2026-08-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: phonelib
@@ -249,6 +249,7 @@ files:
 - app/deserializers/command_tower/deserializers/clients/types.rb
 - app/deserializers/command_tower/deserializers/coercion_result.rb
 - app/deserializers/command_tower/deserializers/failure.rb
+- app/deserializers/command_tower/deserializers/intervention/envelope_deserializer.rb
 - app/deserializers/command_tower/deserializers/me/change_password_deserializer.rb
 - app/deserializers/command_tower/deserializers/me/phone_verification/verify_deserializer.rb
 - app/deserializers/command_tower/deserializers/me/pushover/credentials_deserializer.rb
@@ -353,6 +354,9 @@ files:
 - app/serializers/command_tower/serializers/auth/user_serializer.rb
 - app/serializers/command_tower/serializers/auth/username_availability_serializer.rb
 - app/serializers/command_tower/serializers/impersonation/session_serializer.rb
+- app/serializers/command_tower/serializers/intervention/blocker_serializer.rb
+- app/serializers/command_tower/serializers/intervention/envelope_serializer.rb
+- app/serializers/command_tower/serializers/intervention/remediation_serializer.rb
 - app/serializers/command_tower/serializers/me/account_serializer.rb
 - app/serializers/command_tower/serializers/me/change_password_response_serializer.rb
 - app/serializers/command_tower/serializers/me/pushover_serializer.rb
@@ -760,6 +764,7 @@ files:
 - docs/upgrades/0.10.0.md
 - docs/upgrades/0.11.0.md
 - docs/upgrades/0.11.1.md
+- docs/upgrades/0.12.0.md
 - docs/upgrades/README.md
 - lib/command_tower.rb
 - lib/command_tower/admin_scope.rb