protege 0.1.0.alpha.1

data/app/assets/tailwind/application.css

@@ -0,0 +1,137 @@
+@import "tailwindcss";
+
+/* Scan engine views and helpers for Tailwind class usage */
+@source "../../views/**/*.html.erb";
+@source "../../views/**/*.html.slim";
+@source "../../helpers/**/*.rb";
+
+/* ── Type scale ──────────────────────────────────────────────
+   The dashboard leans on the small end of the ramp (text-xs / text-sm) throughout, which reads
+   cramped at Tailwind's defaults. Retune the scale tokens up one notch here — in one place — so every
+   text-xs/text-sm/… keeps its semantic meaning and simply renders a step larger, rather than scaling
+   the root font-size (which would also stretch rem-based spacing). Line-heights track the defaults.
+*/
+@theme {
+  --text-xs:   0.8125rem;  /* 12 → 13px */
+  --text-sm:   0.9375rem;  /* 14 → 15px */
+  --text-base: 1.0625rem;  /* 16 → 17px */
+  --text-lg:   1.25rem;    /* 18 → 20px */
+}
+
+/* ── Theme tokens ────────────────────────────────────────────
+   Semantic color variables that flip with dark mode.
+   Components use these via arbitrary value syntax:
+     bg-[var(--surface)] text-[var(--text)]
+   or we map them below to utility overrides.
+*/
+:root {
+  --surface:        theme(colors.white);
+  --surface-subtle:  theme(colors.gray.50);
+  --border:         theme(colors.gray.200);
+  --text:           theme(colors.gray.900);
+  --text-muted:     theme(colors.gray.500);
+  --text-faint:     theme(colors.gray.400);
+}
+
+.dark {
+  --surface:        theme(colors.gray.950);
+  --surface-subtle:  theme(colors.gray.900);
+  --border:         theme(colors.gray.800);
+  --text:           theme(colors.gray.100);
+  --text-muted:     theme(colors.gray.400);
+  --text-faint:     theme(colors.gray.600);
+}
+
+/* Apply theme tokens globally */
+body {
+  background-color: var(--surface);
+  color: var(--text);
+}
+
+/* Button hover — light fill on hover for outline buttons */
+.btn-outline:hover {
+  background-color: var(--surface-subtle) !important;
+}
+.btn-danger:hover {
+  background-color: rgba(239, 68, 68, 0.1) !important;
+}
+
+/* Empty-state placeholder for a live container (e.g. the introspection activity feed): shows its
+   data-empty text only while it has no children, so it disappears the moment content streams in. */
+.introspection-empty:empty::before {
+  content: attr(data-empty);
+  color: var(--text-faint);
+  font-size: 0.75rem;
+}
+
+/* Click-to-copy affordance (paired with copy.js). Shows the native copy cursor on hover where the
+   browser supports it, falling back to the hand cursor otherwise (the earlier declaration wins when
+   `copy` is unknown). */
+[data-copy] {
+  cursor: pointer;
+  cursor: copy;
+}
+
+/* Drag-to-resize handle (paired with resize.js). An invisible grab strip laid over a container's edge;
+   its ::before draws the visible divider line, which thickens and brightens on hover so the resize
+   affordance is discoverable. Defaults to a full-height strip on the container's left edge (the common
+   vertical-divider case); override top/right/bottom/left/width/cursor for another edge. */
+.resize-handle {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  left: 0;
+  width: 9px;
+  z-index: 20;
+  cursor: col-resize;
+}
+.resize-handle::before {
+  content: "";
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  left: 0;
+  width: 1px;
+  background: var(--border);
+  transition: width 0.12s ease, background-color 0.12s ease;
+}
+.resize-handle:hover::before,
+.resize-handle:active::before {
+  width: 3px;
+  background: var(--text-faint);
+}
+
+/* Right-edge variant — the divider sits on the container's right edge (e.g. the inbox sidebar). */
+.resize-handle--right {
+  left: auto;
+  right: 0;
+}
+.resize-handle--right::before {
+  left: auto;
+  right: 0;
+}
+
+/* Top-edge variant — a full-width horizontal divider on the container's top edge (e.g. the reply
+   composer), dragged vertically. */
+.resize-handle--top {
+  top: 0;
+  bottom: auto;
+  left: 0;
+  right: 0;
+  width: auto;
+  height: 9px;
+  cursor: row-resize;
+}
+.resize-handle--top::before {
+  top: 0;
+  bottom: auto;
+  left: 0;
+  right: 0;
+  width: auto;
+  height: 1px;
+}
+.resize-handle--top:hover::before,
+.resize-handle--top:active::before {
+  width: auto;
+  height: 3px;
+}

data/app/controllers/concerns/protege/persona_scoped.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Protege
+  # Shared concern for controllers nested under a persona.
+  # Sets +@persona+ from +params[:persona_id]+.
+  module PersonaScoped
+    extend ActiveSupport::Concern
+
+    included do
+      before_action :set_persona
+    end
+
+    private
+
+    # Load the +Persona+ named by +params[:persona_id]+ into +@persona+.
+    #
+    # @return [Protege::Persona] the loaded persona
+    def set_persona
+      @persona = Persona.find(params[:persona_id])
+    end
+  end
+end

data/app/controllers/concerns/protege/thread_scoped.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Protege
+  # Shared concern for controllers nested under a thread.
+  # Sets +@thread+ from +params[:thread_id]+.
+  module ThreadScoped
+    extend ActiveSupport::Concern
+
+    included do
+      before_action :set_thread
+    end
+
+    private
+
+    # Load the +EmailThread+ named by +params[:thread_id]+ into +@thread+.
+    #
+    # @return [Protege::EmailThread] the loaded thread
+    def set_thread
+      @thread = EmailThread.find(params[:thread_id])
+    end
+  end
+end

data/app/controllers/protege/access_rules_controller.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Protege
+  # Manages a persona's runtime inbound access rules — the dashboard-editable, narrowing layer of the
+  # access guardrail (see +AccessRule+ and +AccessControl+). Nested under personas via the
+  # +PersonaScoped+ concern, which loads +@persona+ from +params[:persona_id]+ before every action; each
+  # action renders back to the persona's page.
+  class AccessRulesController < ApplicationController
+    include PersonaScoped
+
+    before_action :set_access_rule, only: [:destroy]
+
+    # Add an access rule to the persona. Serves +POST /personas/:persona_id/access_rules+.
+    #
+    # Turbo requests update the rules table in place (append the row + reset the form on success, or
+    # re-render the form with errors); non-Turbo requests redirect back with the result in the flash.
+    #
+    # @return [void]
+    def create
+      @access_rule = @persona.access_rules.build(access_rule_params)
+      saved        = @access_rule.save
+
+      respond_to do |format|
+        format.turbo_stream { render :create, status: saved ? :ok : :unprocessable_entity }
+        format.html         { redirect_to persona_path(@persona), **create_flash(saved) }
+      end
+    end
+
+    # Remove an access rule from the persona. Serves
+    # +DELETE /personas/:persona_id/access_rules/:id+.
+    #
+    # Turbo requests remove the row in place; non-Turbo requests redirect back to the persona.
+    #
+    # @return [void]
+    def destroy
+      @access_rule.destroy
+
+      respond_to do |format|
+        format.turbo_stream { render turbo_stream: turbo_stream.remove(@access_rule) }
+        format.html         { redirect_to persona_path(@persona), notice: 'Access rule removed.' }
+      end
+    end
+
+    private
+
+    # The flash for the non-Turbo create redirect — a success notice, or the validation errors.
+    #
+    # @param saved [Boolean] whether the rule saved
+    # @return [Hash] the +redirect_to+ flash options
+    def create_flash(saved)
+      if saved
+        { notice: 'Access rule added.' }
+      else
+        { alert: @access_rule.errors.full_messages.to_sentence }
+      end
+    end
+
+    # Load the access rule
+    #
+    # @return [Protege::AccessRule] the access rule to destroy
+    def set_access_rule
+      @access_rule = @persona.access_rules.find(params[:id])
+    end
+
+    # Permit the rule's kind and address pattern.
+    #
+    # @return [ActionController::Parameters] the permitted +:kind+ and +:pattern+
+    def access_rule_params
+      params.require(:access_rule).permit(:kind, :pattern)
+    end
+  end
+end

data/app/controllers/protege/application_controller.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Protege
+  # Base controller for all Protege engine controllers.
+  #
+  # Declares the engine layout explicitly so Rails never falls back to the
+  # host application's layout when rendering engine views.
+  #
+  # Engine route helpers (e.g. +thread_path+) are exposed to views via
+  # +helper+ so they are available in partials rendered both from requests
+  # and from Turbo broadcast rendering.
+  class ApplicationController < ActionController::Base
+    layout 'protege/application'
+
+    helper Protege::ApplicationHelper
+    helper Protege::Engine.routes.url_helpers
+  end
+end

data/app/controllers/protege/archives_controller.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Protege
+  # Archives and unarchives a persona — the reversible, data-preserving alternative to permanent deletion.
+  #
+  # Archiving is modeled as an +archive+ resource on the persona: +create+ archives it (stamps
+  # +archived_at+), +destroy+ unarchives it (clears it). An archived persona stops receiving mail and
+  # running scheduled responsibilities, but all its history is kept and it can be restored at any time.
+  #
+  # Both actions re-render the persona's action bar in place over Turbo (the sidebar row updates
+  # separately via +BroadcastablePersona+), falling back to a full redirect for non-Turbo requests.
+  class ArchivesController < ApplicationController
+    include PersonaScoped
+
+    # Archive the persona. Serves +POST /personas/:persona_id/archive+.
+    #
+    # @return [void]
+    def create
+      @persona.archive!
+
+      respond_with_persona(notice: 'Persona archived — it no longer receives mail or runs scheduled tasks.')
+    end
+
+    # Unarchive the persona. Serves +DELETE /personas/:persona_id/archive+.
+    #
+    # @return [void]
+    def destroy
+      @persona.unarchive!
+
+      respond_with_persona(notice: 'Persona restored.')
+    end
+
+    private
+
+    # Replace the persona's action bar over Turbo, or redirect back to the persona for a full request.
+    #
+    # @param notice [String] the flash message for the redirect fallback
+    # @return [void]
+    def respond_with_persona(notice:)
+      respond_to do |format|
+        format.turbo_stream do
+          render turbo_stream: turbo_stream.replace(
+            helpers.dom_id(@persona, :actions),
+            partial: 'protege/personas/actions',
+            locals:  { persona: @persona }
+          )
+        end
+        format.html { redirect_to persona_path(@persona), notice: }
+      end
+    end
+  end
+end

data/app/controllers/protege/email_domains_controller.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Protege
+  # Manages email domains the engine receives mail for.
+  #
+  # Creating a domain generates a DKIM keypair automatically. The show
+  # page surfaces all DNS records the operator must configure before the
+  # domain goes live.
+  class EmailDomainsController < ApplicationController
+    before_action :set_email_domain, only: %i[show destroy]
+
+    # List every configured email domain, ordered by name. Serves +GET /email_domains+.
+    #
+    # @return [void]
+    def index
+      @email_domains = EmailDomain.order(:domain)
+    end
+
+    # Render the form for adding a new email domain. Serves +GET /email_domains/new+.
+    #
+    # @return [void]
+    def new
+      @email_domain = EmailDomain.new
+    end
+
+    # Create an email domain, generating its DKIM keypair on save. Serves +POST /email_domains+.
+    #
+    # On success, redirect to the show page so the operator can read the DNS
+    # records; on failure, re-render the form with validation errors.
+    #
+    # @return [void]
+    def create
+      @email_domain = EmailDomain.new(email_domain_params)
+
+      if @email_domain.save
+        redirect_to email_domain_path(@email_domain), notice: 'Domain added. Configure the DNS records below.'
+      else
+        render :new, status: :unprocessable_entity
+      end
+    end
+
+    # Show a single domain and the DNS records required to activate it. Serves +GET /email_domains/:id+.
+    #
+    # @return [void]
+    def show; end
+
+    # Delete an email domain. Serves +DELETE /email_domains/:id+.
+    #
+    # @return [void]
+    def destroy
+      @email_domain.destroy!
+
+      redirect_to email_domains_path, notice: 'Domain removed.'
+    end
+
+    private
+
+    # Load the +EmailDomain+ named by +params[:id]+ into +@email_domain+.
+    #
+    # @return [Protege::EmailDomain] the loaded domain
+    def set_email_domain
+      @email_domain = EmailDomain.find(params[:id])
+    end
+
+    # Permit the domain attributes accepted from the new-domain form.
+    #
+    # @return [ActionController::Parameters] the permitted +:domain+ and +:dkim_selector+
+    def email_domain_params
+      params.require(:email_domain).permit(:domain, :dkim_selector)
+    end
+  end
+end

data/app/controllers/protege/home_controller.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Protege
+  # Serves the dashboard landing page mounted at the engine root.
+  #
+  # The page is static — it renders the +show+ view as the entry point into the
+  # Protege dashboard, from which operators navigate to personas, threads, and
+  # email domains.
+  class HomeController < ApplicationController
+    # Render the dashboard landing page. Serves +GET /+.
+    #
+    # @return [void]
+    def show; end
+  end
+end

data/app/controllers/protege/messages_controller.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Protege
+  # Messages — the console email search and per-message delete, both keyed off the globally-unique
+  # message, so neither is thread-scoped.
+  #
+  # +index+ (+GET /messages+) is the cross-persona search view: query params filter the messages via
+  # +MessageSearch+ and the matches render in the sidebar, each linking to its thread. +destroy+
+  # (+DELETE /messages/:id+) removes a single message by id.
+  class MessagesController < ApplicationController
+    before_action :set_message, only: :destroy
+
+    # Search emails across all threads. Serves +GET /messages+ (+?from=&recipients=&subject=&body=
+    # &attachments=&page=+); blank params yield no results.
+    #
+    # @return [void]
+    def index
+      @search   = MessageSearch.from_params(params)
+      @messages = @search.results
+    end
+
+    # Delete a single message. Serves +DELETE /messages/:id+.
+    #
+    # Responds with a Turbo Stream that removes the message element in place, or falls back to
+    # redirecting to its thread for non-Turbo requests.
+    #
+    # @return [void]
+    def destroy
+      @message.destroy!
+
+      respond_to do |format|
+        format.turbo_stream { render turbo_stream: turbo_stream.remove(@message) }
+        format.html         { redirect_to thread_path(@message.email_thread) }
+      end
+    end
+
+    private
+
+    # Load the +Message+ named by +params[:id]+ into +@message+.
+    #
+    # @return [Protege::Message] the loaded message
+    def set_message
+      @message = Message.find(params[:id])
+    end
+  end
+end

data/app/controllers/protege/mta_domains_syncs_controller.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Protege
+  # Pushes the whole domain manifest to the self-hosted MTA on demand — the console "Sync now" button.
+  #
+  # Domain changes already re-provision automatically (+EmailDomain+ enqueues +MailProvisioningJob+ on
+  # commit); this manual re-push is for recovery — e.g. after the accessory was rebooted, or to confirm
+  # the MTA holds the current keys. Nested under a domain for context, but the push is always the full
+  # manifest (the MTA needs complete state), so the specific domain in the URL is incidental.
+  class MtaDomainsSyncsController < ApplicationController
+    # Push the manifest and return to the domain. Serves
+    # +POST /email_domains/:email_domain_id/mta_domains_sync+.
+    #
+    # @return [void]
+    def create
+      result = Gateway.push_mail_provisioning
+
+      redirect_to email_domain_path(params[:email_domain_id]),
+                  flash: { (result[:ok] ? :notice : :alert) => result[:message] }
+    end
+  end
+end

data/app/controllers/protege/personas_controller.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Protege
+  # Manages persona records — listing, creating, viewing, editing, and permanent deletion.
+  #
+  # A persona is the identity behind an inbox; the controller surfaces the full CRUD the dashboard
+  # needs. +destroy+ is the hard, irreversible removal (cascading all the persona's data); the
+  # reversible, history-preserving alternative is archiving — see +ArchivesController+.
+  class PersonasController < ApplicationController
+    before_action :set_persona, only: %i[show edit update destroy]
+
+    # List every persona. Serves +GET /personas+.
+    #
+    # @return [void]
+    def index
+      @personas = Persona.all
+    end
+
+    # Show a single persona. Serves +GET /personas/:id+.
+    #
+    # @return [void]
+    def show; end
+
+    # Render the form for creating a persona. Serves +GET /personas/new+.
+    #
+    # @return [void]
+    def new
+      @persona = Persona.new
+    end
+
+    # Render the form for editing a persona. Serves +GET /personas/:id/edit+.
+    #
+    # @return [void]
+    def edit; end
+
+    # Create a persona from the form's split email fields. Serves +POST /personas+.
+    #
+    # On failure, re-render the form with validation errors.
+    #
+    # @return [void]
+    def create
+      @persona = Persona.new(create_params)
+
+      if @persona.save
+        redirect_to persona_path(@persona), notice: 'Persona created.'
+      else
+        render :new, status: :unprocessable_entity
+      end
+    end
+
+    # Update an existing persona. Serves +PATCH /personas/:id+.
+    #
+    # On failure, re-render the edit form with validation errors.
+    #
+    # @return [void]
+    def update
+      if @persona.update(update_params)
+        redirect_to persona_path(@persona), notice: 'Persona updated.'
+      else
+        render :edit, status: :unprocessable_entity
+      end
+    end
+
+    # Permanently delete a persona and everything it owns. Serves +DELETE /personas/:id+.
+    #
+    # This is the hard, irreversible removal (the reversible path is Archive — see +ArchivesController+):
+    # the model cascades the persona's threads, messages, responsibilities, access rules, and tool-use
+    # history. +BroadcastablePersona+ removes its sidebar row.
+    #
+    # @return [void]
+    def destroy
+      @persona.destroy!
+
+      redirect_to personas_path, notice: 'Persona deleted.'
+    end
+
+    private
+
+    # Load the +Persona+ named by +params[:id]+ into +@persona+.
+    #
+    # @return [Protege::Persona] the loaded persona
+    def set_persona
+      @persona = Persona.find(params[:id])
+    end
+
+    # Permit creation attributes and fold the split email fields into a single address.
+    #
+    # @return [ActionController::Parameters] the permitted attributes plus +:email_address+
+    def create_params
+      params.require(:persona)
+            .permit(:type, :name, :instructions)
+            .merge(email_address: compose_email_address)
+    end
+
+    # Permit the editable attributes and recompose the address from the split email fields. Changing the
+    # address is allowed — only mail to the *old* address stops routing here; all history keys off
+    # +persona_id+, not the address. +disabled_tool_ids+ is the tool checklist submitted straight from
+    # the form (the model strips the hidden blank); a PATCH without that field leaves the scope untouched.
+    #
+    # @return [ActionController::Parameters] the permitted attributes plus +:email_address+
+    def update_params
+      params.require(:persona)
+            .permit(:name, :instructions, disabled_tool_ids: [])
+            .merge(email_address: compose_email_address)
+    end
+
+    # Combine the split prefix + domain fields from the form into a single
+    # email address.
+    #
+    # @return [String] the +prefix@domain+ address with surrounding whitespace stripped
+    def compose_email_address
+      params[:persona].values_at(:email_prefix, :email_domain)
+                      .map(&:to_s)
+                      .map(&:strip)
+                      .join('@')
+    end
+  end
+end

data/app/controllers/protege/replies_controller.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Protege
+  # Handles replies within an existing thread from the dashboard
+  # console. Nested under threads via the +ThreadScoped+ concern, which loads
+  # +@thread+ from +params[:thread_id]+.
+  class RepliesController < ApplicationController
+    include ThreadScoped
+
+    # Build a reply mail and hand it to the +Gateway+ for inbound processing.
+    # Serves +POST /threads/:thread_id/reply+.
+    #
+    # The console acts as the sender; the reply is addressed to the thread's
+    # persona so the LOGI loop processes it as if it arrived over SMTP.
+    #
+    # The new message inserts itself into the thread over Turbo (its +after_create_commit+ broadcast,
+    # see +BroadcastableMessage+), so a Turbo request needs no body — it just returns +201 Created+, which
+    # Turbo treats as "handled, no navigation". Skipping the redirect keeps the live introspection panel
+    # intact, so a new run appends below the prior ones instead of resetting. Non-Turbo clients redirect.
+    #
+    # @return [void]
+    def create
+      Gateway.accept_console_message(
+        mail:        build_reply_mail,
+        persona:     @thread.persona,
+        attachments: reply_params[:files] || []
+      )
+
+      respond_to do |format|
+        format.turbo_stream { head :created }
+        format.html { redirect_to thread_path(@thread) }
+      end
+    end
+
+    private
+
+    # Permit the reply body and any uploaded files submitted from the console form.
+    #
+    # @return [ActionController::Parameters] the permitted +:body+ and +:files+
+    def reply_params
+      params.require(:reply).permit(:body, files: [])
+    end
+
+    # Construct a threaded reply +Mail+ object from the console.
+    #
+    # Threads the message by chaining +In-Reply-To+ to the last message and +References+ to every
+    # prior message ID, preserving the conversation. Assembly (synthetic id, charset, date, threading
+    # header normalization) is delegated to +Gateway.build_outbound+.
+    #
+    # @return [Mail::Message] the composed reply ready for the +Gateway+
+    def build_reply_mail
+      messages = @thread.messages.order(:sent_at)
+
+      Gateway.build_outbound(
+        from:        Protege.configuration.console_address,
+        to:          @thread.persona.email_address,
+        subject:     @thread.subject,
+        body:        reply_params[:body],
+        in_reply_to: messages.last&.message_id,
+        references:  messages.pluck(:message_id)
+      )
+    end
+  end
+end