collavre 0.24.0 → 0.25.0

data/lib/collavre/engine.rb

@@ -1,11 +1,41 @@
+require "collavre/sensitive_request_silencer"
+require "collavre/hashed_access_token_lookup"
+
 module Collavre
   class Engine < ::Rails::Engine
+    PROVISIONING_CAPABILITY_PATH = %r{
+      \A(?:/[^/]+)*/agents/\d+/workspaces/[^/]+(?:/.*)?\z
+    }x
+
     isolate_namespace Collavre
 
     config.generators do |g|
       g.test_framework :minitest
     end
 
+    # Manifest capabilities grant access to workspace callback credentials and
+    # therefore must not appear in Rails request logs. This middleware wraps the
+    # request logger as well as controller instrumentation while leaving public,
+    # content-addressed skill archive requests observable.
+    initializer "collavre.silence_provisioning_capability_paths" do |app|
+      app.middleware.insert_before(
+        Rails::Rack::Logger,
+        Collavre::SensitiveRequestSilencer,
+        path: PROVISIONING_CAPABILITY_PATH
+      )
+    end
+
+    # Workspace callback credentials retain their plaintext only in the
+    # encrypted AgentWorkspace column. Doorkeeper stores a one-way digest and
+    # resolves presented bearer values through this mixed plain/hashed lookup,
+    # preserving existing OAuth tokens without making stored digests usable.
+    initializer "collavre.hashed_workspace_callback_tokens" do
+      Rails.application.config.to_prepare do
+        token_class = Doorkeeper::AccessToken.singleton_class
+        token_class.prepend(Collavre::HashedAccessTokenLookup) unless token_class < Collavre::HashedAccessTokenLookup
+      end
+    end
+
     # Path to engine's JavaScript sources for jsbundling-rails integration
     def self.javascript_path
       root.join("app/javascript")
@@ -148,6 +178,83 @@ module Collavre
       ActiveSupport::Reloader.to_prepare(prepend: true) do
         Navigation::Registry.instance.reset!
         Collavre::ViewExtensions.reset!
+        Collavre::FeatureCardRegistry.reset!
+      end
+    end
+
+    # Register the empty-chat feature discovery cards. Vendor engines may
+    # register additional cards from their own initializers (after this one)
+    # the same way they register integrations.
+    initializer "collavre.feature_cards", after: "collavre.navigation_reset" do
+      Rails.application.config.to_prepare do
+        Collavre::FeatureCardRegistry.register(:mention_agent, {
+          icon: "🤖",
+          title_key: "collavre.comments.empty_state.cards.mention_agent.title",
+          description_key: "collavre.comments.empty_state.cards.mention_agent.description",
+          guide: true
+        })
+
+        Collavre::FeatureCardRegistry.register(:slash_command, {
+          icon: "⚡",
+          title_key: "collavre.comments.empty_state.cards.slash_command.title",
+          description_key: "collavre.comments.empty_state.cards.slash_command.description",
+          action: { type: :command_menu, label_key: "collavre.comments.empty_state.cards.slash_command.action" },
+          guide: true
+        })
+
+        Collavre::FeatureCardRegistry.register(:chat_context, {
+          icon: "🔗",
+          title_key: "collavre.comments.empty_state.cards.chat_context.title",
+          description_key: "collavre.comments.empty_state.cards.chat_context.description",
+          guide: true
+        })
+
+        Collavre::FeatureCardRegistry.register(:automation_trigger, {
+          icon: "⚙️",
+          title_key: "collavre.comments.empty_state.cards.automation_trigger.title",
+          description_key: "collavre.comments.empty_state.cards.automation_trigger.description",
+          guide: true
+        })
+
+        Collavre::FeatureCardRegistry.register(:topic_management, {
+          icon: "🗂️",
+          title_key: "collavre.comments.empty_state.cards.topic_management.title",
+          description_key: "collavre.comments.empty_state.cards.topic_management.description",
+          action: { type: :topic_list, label_key: "collavre.comments.empty_state.cards.topic_management.action" },
+          guide: true
+        })
+
+        Collavre::FeatureCardRegistry.register(:add_user, {
+          icon: "👥",
+          title_key: "collavre.comments.empty_state.cards.add_user.title",
+          description_key: "collavre.comments.empty_state.cards.add_user.description",
+          action: { type: :share_modal, label_key: "collavre.comments.empty_state.cards.add_user.action" },
+          guide: true
+        })
+
+        Collavre::FeatureCardRegistry.register(:inbox_notifications, {
+          icon: "🔔",
+          title_key: "collavre.comments.empty_state.cards.inbox_notifications.title",
+          description_key: "collavre.comments.empty_state.cards.inbox_notifications.description",
+          surfaces: [ :inbox_system ],
+          guide: true
+        })
+
+        Collavre::FeatureCardRegistry.register(:inbox_reply, {
+          icon: "↩️",
+          title_key: "collavre.comments.empty_state.cards.inbox_reply.title",
+          description_key: "collavre.comments.empty_state.cards.inbox_reply.description",
+          surfaces: [ :inbox_system ],
+          guide: true
+        })
+
+        Collavre::FeatureCardRegistry.register(:inbox_source, {
+          icon: "🔗",
+          title_key: "collavre.comments.empty_state.cards.inbox_source.title",
+          description_key: "collavre.comments.empty_state.cards.inbox_source.description",
+          surfaces: [ :inbox_system ],
+          guide: true
+        })
       end
     end
 
@@ -178,7 +285,7 @@ module Collavre
           key: :home,
           label: "app.home",
           type: :button,
-          path: -> { main_app.root_path },
+          path: -> { home_navigation_path }, html_class: "home-nav-button",
           priority: 110
         )
 

data/lib/collavre/feature_card_registry.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module Collavre
+  # Registry for the empty-chat "feature discovery" cards shown when a
+  # Creative's comment thread has no comments yet. Mirrors the
+  # Collavre::IntegrationRegistry pattern so vendor engines can register
+  # their own cards later without touching the core empty-state view.
+  #
+  # @example Registering a card
+  #   Collavre::FeatureCardRegistry.register(:add_user, {
+  #     icon: "user-plus",
+  #     title_key: "collavre.comments.empty_state.cards.add_user.title",
+  #     description_key: "collavre.comments.empty_state.cards.add_user.description",
+  #     action: { type: :share_modal },
+  #     guide: true
+  #   })
+  class FeatureCardRegistry
+    include Singleton
+
+    def initialize
+      @cards = {}
+      @mutex = Mutex.new
+    end
+
+    # Register a new feature card
+    # @param key [Symbol] Unique identifier for the card
+    # @param config [Hash] Configuration options
+    # @option config [String] :icon Icon identifier (optional)
+    # @option config [String] :title_key i18n key for the card title
+    # @option config [String] :description_key i18n key for the card description
+    # @option config [Array<Symbol>] :surfaces Empty-state surfaces where the card appears
+    #   (defaults to [:default])
+    # @option config [Hash] :action Optional { type:, label_key: } describing a call-to-action button
+    # @option config [Boolean] :guide Opt in to the engine-provided public guide page at
+    #   collavre.feature_path(key). Only set this once the page's copy exists under
+    #   collavre.features.pages.<key> — FeaturesController#show 404s for cards without it.
+    # @option config [String] :guide_url Optional URL overriding the engine guide page, for
+    #   vendor engines that host their own documentation.
+    def register(key, config)
+      card = FeatureCard.new(key, config)
+      @mutex.synchronize do
+        @cards[key.to_sym] = card
+      end
+      card
+    end
+
+    def unregister(key)
+      @mutex.synchronize do
+        @cards.delete(key.to_sym)
+      end
+    end
+
+    def find(key)
+      @mutex.synchronize do
+        @cards[key.to_sym]
+      end
+    end
+
+    def all
+      @mutex.synchronize do
+        @cards.values
+      end
+    end
+
+    def for(creative:, topic:)
+      surface = if creative.inbox? && topic&.name == Creative::SYSTEM_TOPIC_NAME
+        :inbox_system
+      else
+        :default
+      end
+
+      all.select { |card| card.visible_on?(surface) }
+    end
+
+    # Cards that render on the public /features hub — only those opting into the
+    # engine-provided guide page, since a vendor card pointing at its own
+    # :guide_url has no page here to link to.
+    def with_builtin_guide
+      all.select(&:builtin_guide?)
+    end
+
+    def each(&block)
+      all.each(&block)
+    end
+
+    def any?
+      @mutex.synchronize do
+        @cards.any?
+      end
+    end
+
+    # Clear all cards (useful for testing)
+    def reset!
+      @mutex.synchronize do
+        @cards = {}
+      end
+    end
+
+    class << self
+      delegate :register, :unregister, :find, :all, :for, :with_builtin_guide, :each, :any?, :reset!, to: :instance
+    end
+  end
+
+  # Represents a registered feature card
+  class FeatureCard
+    # A card with a built-in guide has its key placed in a URL by
+    # collavre.feature_path, so it has to satisfy the :key constraint on the
+    # features route. config/routes.rb uses this verbatim; Rails rejects anchors
+    # in a routing requirement and anchors the segment itself, so the anchored
+    # form below is what validation compares against.
+    GUIDE_KEY_FORMAT = /[a-z0-9_]+/
+    GUIDE_KEY_FORMAT_ANCHORED = /\A#{GUIDE_KEY_FORMAT.source}\z/
+
+    attr_reader :key, :icon, :title_key, :description_key, :action, :guide_url, :surfaces
+
+    def initialize(key, config)
+      @key = key.to_sym
+      @icon = config[:icon]
+      @title_key = config[:title_key]
+      @description_key = config[:description_key]
+      @action = config[:action]
+      @guide = config.fetch(:guide, false)
+      @guide_url = config[:guide_url]
+      @surfaces = Array(config.fetch(:surfaces, :default)).map(&:to_sym).uniq.freeze
+
+      validate!
+    end
+
+    def guide_url?
+      @guide_url.present?
+    end
+
+    # True when this card is served by the engine's own /features/:key page.
+    # A card carrying its own :guide_url is documented elsewhere, so the engine
+    # neither renders nor routes a page for it.
+    def builtin_guide?
+      @guide && !guide_url?
+    end
+
+    # True when the empty-state card should render a "learn more" link at all.
+    def guide_link?
+      builtin_guide? || guide_url?
+    end
+
+    def visible_on?(surface)
+      @surfaces.include?(surface.to_sym)
+    end
+
+    private
+
+    def validate!
+      raise ArgumentError, "FeatureCard must have a :title_key" unless @title_key.present?
+      raise ArgumentError, "FeatureCard must have a :description_key" unless @description_key.present?
+      raise ArgumentError, "FeatureCard must have at least one :surface" if @surfaces.empty?
+
+      # Reject an unroutable key at registration rather than at render. A key the
+      # features route cannot accept would otherwise raise UrlGenerationError from
+      # feature_path, turning an extension's typo into a 500 on a user's empty
+      # chat and on the public hub. Fail loudly at boot, where the author sees it.
+      return unless @guide && !guide_url?
+      return if @key.to_s.match?(GUIDE_KEY_FORMAT_ANCHORED)
+
+      raise ArgumentError,
+            "FeatureCard key #{@key.inspect} cannot use the built-in guide page: " \
+            "keys must match #{GUIDE_KEY_FORMAT_ANCHORED.inspect}. Supply a :guide_url instead."
+    end
+  end
+end

data/lib/collavre/hashed_access_token_lookup.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Collavre
+  module HashedAccessTokenLookup
+    PREFIX = "sha256$"
+
+    class << self
+      def encode(plaintext)
+        "#{PREFIX}#{Digest::SHA256.hexdigest(plaintext.to_s)}"
+      end
+    end
+
+    def by_token(plaintext)
+      value = plaintext.to_s
+      return if value.start_with?(PREFIX)
+
+      super || find_by(token: HashedAccessTokenLookup.encode(value))
+    end
+  end
+end

data/lib/collavre/sensitive_request_silencer.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "active_support/logger_silence"
+
+module Collavre
+  # Prevents capability-bearing request paths from reaching any Rails log level.
+  # Logger::UNKNOWN + 1 is intentional: the built-in SilenceRequest defaults to
+  # ERROR, which still permits exception logs containing the original path.
+  class SensitiveRequestSilencer
+    SILENCE_LEVEL = ::Logger::UNKNOWN + 1
+
+    def initialize(app, path:)
+      @app = app
+      @path = path
+    end
+
+    def call(env)
+      return @app.call(env) unless @path === env["PATH_INFO"]
+
+      Rails.logger.silence(SILENCE_LEVEL) { @app.call(env) }
+    end
+  end
+end

data/lib/collavre/user_extensions.rb

@@ -10,8 +10,6 @@ module Collavre
       has_many :collavre_shared_creative_shares, class_name: "Collavre::CreativeShare",
                foreign_key: :shared_by_id, dependent: :nullify, inverse_of: :shared_by
       has_many :collavre_topics, class_name: "Collavre::Topic", dependent: :destroy
-      has_many :collavre_inbox_items, class_name: "Collavre::InboxItem",
-               foreign_key: :owner_id, dependent: :destroy, inverse_of: :owner
       has_many :collavre_invitations, class_name: "Collavre::Invitation",
                foreign_key: :inviter_id, dependent: :destroy, inverse_of: :inviter
       has_many :collavre_contacts, class_name: "Collavre::Contact", dependent: :destroy

data/lib/collavre/version.rb

@@ -1,3 +1,3 @@
 module Collavre
-  VERSION = "0.24.0"
+  VERSION = "0.25.0"
 end

data/lib/collavre.rb

@@ -3,6 +3,7 @@ require "collavre/configuration"
 require "collavre/engine"
 require "collavre/user_extensions"
 require "collavre/integration_registry"
+require "collavre/feature_card_registry"
 require "collavre/integration_settings"
 require "collavre/aws_credentials"
 require "collavre/ses_settings_interceptor"

data/skills/collavre/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: collavre
+description: Manage Collavre Creatives (hierarchical tasks/content blocks) via CLI. Use when creating, retrieving, updating, importing, or batch-operating on Creatives. Creatives are tree-structured items with automatic progress rollup — like a smart to-do list that doubles as a structured document.
+---
+
+# Collavre
+
+CLI for managing Collavre Creatives via MCP protocol.
+
+## Setup
+
+```bash
+# Configure (once)
+collavre auth --url https://collavre.example.com --token <oauth_token>
+
+# Verify
+collavre list
+```
+
+The `collavre` script lives in `scripts/collavre`. Config is stored at `~/.config/collavre/config.json`.
+
+## Commands
+
+### List root creatives
+```bash
+collavre list
+collavre list --level 5              # deeper tree
+collavre list --format json          # structured output
+```
+
+### Get a creative subtree
+```bash
+collavre get 123
+collavre get 123 --level 5 --comments
+```
+
+### Search
+```bash
+collavre search "project name"
+collavre search "urgent" --tags "v2"
+```
+
+### Create
+```bash
+collavre create --parent 123 --desc "New task"
+collavre create --parent 123 --desc "# Rich content\n\n- point one\n- point two"
+```
+
+### Update
+```bash
+collavre update 456 --desc "Updated title"
+collavre update 456 --progress 1.0        # mark complete (leaf only)
+collavre update 456 --parent 789           # move
+```
+
+### Import markdown
+```bash
+collavre import --parent 123 --file plan.md
+collavre import --parent 123 --stdin < plan.md
+echo "# Quick\n## Plan" | collavre import --parent 123 --stdin
+```
+
+### Attach a file
+```bash
+collavre attach --creative 123 --file ./hero.png    # png/mp4/pdf/svg
+```
+Uploads the raw bytes over a bearer multipart endpoint, embeds the matching
+node (`<img>`/`<video>`/`<a>`) into the creative's description, and attaches the
+blob to `creative.files`. Use this for binary files on disk. For inline
+agent-generated text (markdown/html/svg source), use the
+`creative_attach_files_service` tool with `files: [{ filename, content }]`.
+
+### Batch operations
+```bash
+collavre batch --file ops.json
+```
+
+ops.json format:
+```json
+[
+  { "action": "create", "parent_id": 100, "description": "Task A" },
+  { "action": "update", "id": 200, "progress": 1.0 },
+  { "action": "delete", "id": 300 }
+]
+```
+
+### Topics and messages
+
+Topics are conversation threads on a Creative — and the unit of agent
+concurrency. Tasks in the same topic are serialized (one runs, the rest queue);
+tasks in different topics run in parallel. There is no dedicated CLI verb yet;
+drive them through `collavre tool run`:
+
+```bash
+# See what topics exist and how much conversation each holds
+collavre tool run topic_list --json '{"creative_id": 8849}'
+
+# Summarize three topics at once — first page only; offset/limit apply per topic
+collavre tool run topic_messages --json '{"topic_ids": "12,45,78", "limit": 100}'
+
+# Continue each topic separately with its own cursor and snapshot id
+collavre tool run topic_messages --json '{"topic_ids": 12, "offset": 100, "cursor": "1770000000000000:989:1770000001000000:1770000002000000", "max_message_id": 9931}'
+
+# Continue inside one clipped message, preserving its row cursor
+collavre tool run topic_messages --json '{"topic_ids": 12, "offset": 100, "cursor": "1770000000000000:989:1770000001000000:1770000002000000", "content_offset": 28400, "max_message_id": 9931}'
+
+# Fan work out: one topic per unit of work, with an agent pinned to each;
+# keep each returned topic id for the initial-message calls
+collavre tool run topic_create --json '{"creative_id": 8849, "name": "Research", "primary_agent": "Dev1Claude"}'
+collavre tool run topic_create --json '{"creative_id": 8849, "name": "Delivery", "primary_agent": "Dev1Claude"}'
+
+# Start the pinned agent independently in both topics
+collavre tool run topic_message_create --json '{"topic_id": 12, "content": "Research the API options and report your recommendation."}'
+collavre tool run topic_message_create --json '{"topic_id": 13, "content": "Build the selected approach and verify it."}'
+
+# Put a finished thread away (messages are kept and stay readable by id)
+collavre tool run topic_update --json '{"topic_id": 12, "archived": true}'
+
+# Move a complete thread, including its messages and read cursors
+collavre tool run topic_move --json '{"topic_id": 13, "creative_id": 9023}'
+
+# Carry the messages that still matter into a fresh topic
+collavre tool run topic_branch --json '{"source_topic_id": 12, "comment_ids": "991,994"}'
+```
+
+`topic_messages` includes each comment image as a URL-bearing marker in the
+message content. Image-only comments are not blank, and a long attachment list
+uses the same `content_offset` continuation as long prose.
+
+### Discover & run tools (meta)
+```bash
+collavre tool list                                # list available tools
+collavre tool list --full                         # list with full details
+collavre tool search "github"                     # search by name/description
+collavre tool info <tool_name>                    # show tool parameters
+collavre tool run <tool_name> --json '{"k":"v"}'  # run with JSON args
+collavre tool run <tool_name> --key value         # run with flag args
+```
+
+## Key Concepts
+
+- **Tree structure**: Creatives nest via `parent_id`. Use `--level` to control depth.
+- **Topics**: conversation threads on a Creative, and the concurrency unit — same
+  topic serializes, different topics run in parallel. One topic = one thread
+  reaching one conclusion; archive it when it gets there rather than reusing it.
+- **Primary agent**: pinning an agent to a topic is exclusive — that agent alone
+  answers there. Use it for a dedicated 1:1 channel; leave it unset for a thread
+  several participants should hear.
+- **Starting topic work**: after creating and pinning a topic, call
+  `topic_message_create` with its initial instruction. Agent-authored messages
+  dispatch as A2A work, so one coordinating agent can start independent work in
+  several topics without impersonating a human. Do not call it on the topic the
+  caller is currently handling; continue that work in the current turn instead.
+- **Moving topics**: `topic_move` keeps the thread and its messages together,
+  but Creative permissions stay with each Creative. Verify that participants
+  can access the destination after moving. Wait for or cancel active agent work
+  in the topic before moving it, and wait for dropped-message restoration to
+  settle. Cancel recurring cron jobs that target the topic and recreate them
+  after the move. Topics referenced by a Drop Trigger loop cannot move.
+- **Progress**: Leaf = manual (0.0 or 1.0). Parent = auto-calculated from children.
+- **Import**: Markdown headings/bullets become nested Creatives.
+- **Batch**: All-or-nothing transaction. Requires approval.
+- **Description format**: Written as Markdown (GitHub-Flavored: headings, bold/italic, lists, links, tables, code blocks, task lists). A single newline is a line break. Plain text is stored as-is.
+
+For detailed MCP tool parameters, see [references/tool-reference.md](references/tool-reference.md).

data/skills/collavre/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "collavre-cli",
+  "version": "1.0.0",
+  "type": "module",
+  "bin": {
+    "collavre": "./scripts/collavre"
+  }
+}