trak_flow 0.1.3 → 0.2.0

data/lib/trak_flow/graph/dependency_graph.rb

@@ -87,30 +87,10 @@ module TrakFlow
         tasks = task_ids.map { |id| @db.find_task(id) }.compact
         tasks = tasks.reject(&:closed?) unless include_closed
 
-        lines = ["digraph dependencies {"]
-        lines << '  rankdir=TB;'
-        lines << '  node [shape=box, style=filled];'
+        lines = ["digraph dependencies {", "  rankdir=TB;", "  node [shape=box, style=filled];", ""]
+        lines.concat(dot_node_lines(tasks))
         lines << ""
-
-        tasks.each do |task|
-          color = node_color(task)
-          label = "#{task.id}\\n#{truncate(task.title, 30)}"
-          lines << "  \"#{task.id}\" [label=\"#{label}\", fillcolor=\"#{color}\"];"
-        end
-
-        lines << ""
-
-        task_set = Set.new(tasks.map(&:id))
-
-        tasks.each do |task|
-          @db.find_dependencies(task.id, direction: :outgoing).each do |dep|
-            next unless task_set.include?(dep.target_id)
-
-            style = edge_style(dep)
-            lines << "  \"#{dep.source_id}\" -> \"#{dep.target_id}\" [#{style}];"
-          end
-        end
-
+        lines.concat(dot_edge_lines(tasks))
         lines << "}"
         lines.join("\n")
       end
@@ -127,7 +107,7 @@ module TrakFlow
         end
 
         # Make background transparent for dark theme compatibility
-        stdout.gsub(/fill="white"/, 'fill="none"')
+        stdout.gsub('fill="white"', 'fill="none"')
       end
 
       # Analyze the graph for potential problems
@@ -144,28 +124,40 @@ module TrakFlow
 
       private
 
+      def dot_node_lines(tasks)
+        tasks.map do |task|
+          id = task.id
+          label = "#{id}\\n#{truncate(task.title, 30)}"
+          "  \"#{id}\" [label=\"#{label}\", fillcolor=\"#{node_color(task)}\"];"
+        end
+      end
+
+      # Edges are drawn only between tasks that are both in the graph.
+      def dot_edge_lines(tasks)
+        task_set = Set.new(tasks.map(&:id))
+
+        tasks.flat_map do |task|
+          @db.find_dependencies(task.id, direction: :outgoing)
+             .select { |dep| task_set.include?(dep.target_id) }
+             .map { |dep| "  \"#{dep.source_id}\" -> \"#{dep.target_id}\" [#{edge_style(dep)}];" }
+        end
+      end
+
       def build_tree_node(task, direction, remaining_depth, visited)
-        return nil if remaining_depth <= 0 || visited.include?(task.id)
+        task_id = task.id
+        return nil if remaining_depth <= 0 || visited.include?(task_id)
 
-        visited << task.id
+        visited << task_id
 
         node = {
-          id: task.id,
+          id: task_id,
           title: task.title,
           status: task.status,
           priority: task.priority,
           children: []
         }
 
-        dep_direction = direction == :blocking ? :incoming : :outgoing
-        deps = @db.find_dependencies(task.id, direction: dep_direction)
-        deps = deps.select(&:blocking?) if direction == :blocking
-
-        deps.each do |dep|
-          related_id = direction == :blocking ? dep.source_id : dep.target_id
-          related_task = @db.find_task(related_id)
-          next unless related_task
-
+        related_tasks(task_id, direction).each do |related_task|
           child_node = build_tree_node(related_task, direction, remaining_depth - 1, visited.dup)
           node[:children] << child_node if child_node
         end
@@ -173,6 +165,16 @@ module TrakFlow
         node
       end
 
+      # Tasks one dependency hop away from task_id. In :blocking direction only
+      # blocking incoming deps count; otherwise all outgoing deps do.
+      def related_tasks(task_id, direction)
+        blocking = direction == :blocking
+        deps = @db.find_dependencies(task_id, direction: blocking ? :incoming : :outgoing)
+        deps = deps.select(&:blocking?) if blocking
+
+        deps.filter_map { |dep| @db.find_task(blocking ? dep.source_id : dep.target_id) }
+      end
+
       def collect_related_tasks(start_id, direction, types)
         visited = Set.new
         queue = [start_id]
@@ -184,24 +186,24 @@ module TrakFlow
 
           visited << current_id
 
-          deps = @db.find_dependencies(current_id, direction: direction)
-          deps = deps.select { |d| types.include?(d.type) }
-
-          deps.each do |dep|
-            related_id = direction == :incoming ? dep.source_id : dep.target_id
-            next if visited.include?(related_id)
-
-            task = @db.find_task(related_id)
-            if task
-              result << task
-              queue << related_id
-            end
+          unvisited_related_tasks(current_id, direction, types, visited).each do |task|
+            result << task
+            queue << task.id
           end
         end
 
         result
       end
 
+      def unvisited_related_tasks(current_id, direction, types, visited)
+        @db.find_dependencies(current_id, direction: direction)
+           .select { |d| types.include?(d.type) }
+           .filter_map do |dep|
+             related_id = direction == :incoming ? dep.source_id : dep.target_id
+             @db.find_task(related_id) unless visited.include?(related_id)
+           end
+      end
+
       def find_longest_path(task_id, memo)
         return memo[task_id] if memo.key?(task_id)
 
@@ -234,17 +236,17 @@ module TrakFlow
         bottlenecks = []
 
         @db.list_tasks(status: "open").each do |task|
-          incoming = @db.find_dependencies(task.id, direction: :incoming).count
-          outgoing = @db.find_dependencies(task.id, direction: :outgoing).count
-
-          if incoming >= 3 || outgoing >= 3
-            bottlenecks << {
-              id: task.id,
-              title: task.title,
-              incoming_deps: incoming,
-              outgoing_deps: outgoing
-            }
-          end
+          id = task.id
+          incoming = @db.find_dependencies(id, direction: :incoming).count
+          outgoing = @db.find_dependencies(id, direction: :outgoing).count
+
+          next unless incoming >= 3 || outgoing >= 3
+          bottlenecks << {
+            id: id,
+            title: task.title,
+            incoming_deps: incoming,
+            outgoing_deps: outgoing
+          }
         end
 
         bottlenecks.sort_by { |b| -(b[:incoming_deps] + b[:outgoing_deps]) }
@@ -254,26 +256,27 @@ module TrakFlow
         status_color = COLORS[:status][task.status.to_sym]
         return status_color if status_color
 
+        priorities = COLORS[:priority]
         priority_colors = {
-          0 => COLORS[:priority][:critical],
-          1 => COLORS[:priority][:high],
-          2 => COLORS[:priority][:medium],
-          3 => COLORS[:priority][:low]
+          0 => priorities[:critical],
+          1 => priorities[:high],
+          2 => priorities[:medium],
+          3 => priorities[:low]
         }
-        priority_colors[task.priority] || COLORS[:priority][:backlog]
+        priority_colors[task.priority] || priorities[:backlog]
       end
 
       def edge_style(dep)
-        type_key = dep.type.tr("-", "_").to_sym
-        color = COLORS[:edge][type_key]
+        type = dep.type
+        color = COLORS[:edge][type.tr("-", "_").to_sym]
         return "" unless color
 
-        style = case dep.type
+        style = case type
                 when "blocks" then "bold"
-                when "parent-child", "related", "discovered-from" then "dashed"
+                when "parent-child" then "dashed"
+                when "related", "discovered-from" then "dotted"
                 else "solid"
                 end
-        style = "dotted" if %w[related discovered-from].include?(dep.type)
 
         %(color="#{color}", style=#{style})
       end

data/lib/trak_flow/mcp/resources/dependency_graph.rb

@@ -12,19 +12,23 @@ module TrakFlow
         def content
           self.class.with_database do |db|
             tasks = db.list_tasks
-            nodes = tasks.map { |t| { id: t.id, title: t.title, status: t.status } }
 
-            edges = []
-            tasks.each do |task|
-              db.find_dependencies(task.id, direction: :outgoing).each do |dep|
-                edges << { source: dep.source_id, target: dep.target_id, type: dep.type }
-              end
-            end
-
-            result = { nodes: nodes, edges: edges }
+            result = {
+              nodes: tasks.map { |t| { id: t.id, title: t.title, status: t.status } },
+              edges: edges_for(db, tasks)
+            }
             Oj.dump(result, mode: :compat, indent: 2)
           end
         end
+
+        private
+
+        def edges_for(db, tasks)
+          tasks.flat_map do |task|
+            db.find_dependencies(task.id, direction: :outgoing)
+              .map { |dep| { source: dep.source_id, target: dep.target_id, type: dep.type } }
+          end
+        end
       end
     end
   end

data/lib/trak_flow/mcp/resources/task_by_id.rb

@@ -12,9 +12,10 @@ module TrakFlow
         def content
           self.class.with_database do |db|
             task = db.find_task!(params[:id])
-            labels = db.find_labels(task.id)
-            deps = db.find_dependencies(task.id)
-            comments = db.find_comments(task.id)
+            task_id = task.id
+            labels = db.find_labels(task_id)
+            deps = db.find_dependencies(task_id)
+            comments = db.find_comments(task_id)
 
             result = {
               task: task.to_h,

data/lib/trak_flow/mcp/server.rb

@@ -1,10 +1,6 @@
 # frozen_string_literal: true
 
 require "fast_mcp"
-require "puma"
-require "puma/configuration"
-require "rack"
-require "rackup"
 
 module TrakFlow
   module Mcp
@@ -25,30 +21,16 @@ module TrakFlow
         mcp_server.start
       end
 
-      def start_http(port: nil)
+      def start_http(port: nil, handler: nil)
+        require_http_transport_gems
         port ||= TrakFlow.config.mcp.port
         puts "Starting TrakFlow MCP Server (HTTP transport on port #{port})..."
 
-        rack_app = create_rack_app
-
-        # Configure Puma (supports rack.hijack for SSE)
-        puma_config = Puma::Configuration.new do |config|
-          config.bind "tcp://0.0.0.0:#{port}"
-          config.threads 1, 5
-          config.workers 0
-          config.quiet
-          config.app rack_app
-        end
-
-        launcher = Puma::Launcher.new(puma_config)
-
-        trap("INT") { launcher.stop }
-        trap("TERM") { launcher.stop }
-
-        launcher.run
+        start_http_server(port, handler)
       end
 
-      def start_both(http_port: nil)
+      def start_both(http_port: nil, handler: nil)
+        require_http_transport_gems
         http_port ||= TrakFlow.config.mcp.port
         puts "Starting TrakFlow MCP Server (dual transport)..."
         puts "  - HTTP: port #{http_port}"
@@ -56,7 +38,7 @@ module TrakFlow
 
         # Start HTTP in a thread
         http_thread = Thread.new do
-          start_http_server(http_port)
+          start_http_server(http_port, handler)
         end
 
         # Run STDIO in main thread (blocking)
@@ -65,9 +47,20 @@ module TrakFlow
         http_thread.join
       end
 
-      private
+      # The MCP transport as a plain Rack application. Public so a host app
+      # that already runs its own Rack server can mount it there instead of
+      # letting trak_flow boot a second server:
+      #
+      #   # config.ru of the host app
+      #   map "/mcp" do
+      #     run TrakFlow::Mcp::Server.new.rack_app
+      #   end
+      #
+      # The host's server must support rack.hijack for SSE (Puma, Falcon,
+      # WEBrick, iodine all do).
+      def rack_app
+        require "rack"
 
-      def create_rack_app
         server = mcp_server
         Rack::Builder.new do
           use FastMcp::Transports::RackTransport, server
@@ -75,65 +68,73 @@ module TrakFlow
         end.to_app
       end
 
-      def start_http_server(port)
-        rack_app = create_rack_app
-
-        # Configure Puma (supports rack.hijack for SSE)
-        puma_config = Puma::Configuration.new do |config|
-          config.bind "tcp://0.0.0.0:#{port}"
-          config.threads 1, 5
-          config.workers 0
-          config.quiet
-          config.app rack_app
-        end
+      # The Rack server that will run the HTTP transport, resolved through
+      # the generic Rackup handler interface so any registered server works.
+      # Priority: the explicit argument, then TrakFlow.config.mcp.handler
+      # (or the TF_MCP__HANDLER env var), then Rackup's default lookup —
+      # which picks a server already in the bundle (puma, falcon, webrick).
+      def http_handler(handler_name = nil)
+        handler_name ||= TrakFlow.config.mcp.handler
+        handler_name ? Rackup::Handler.get(handler_name) : Rackup::Handler.default
+      rescue LoadError, NameError => e
+        raise LoadError,
+              "No usable Rack server#{" for handler '#{handler_name}'" if handler_name} found in the bundle. " \
+              'Add one that supports rack.hijack — e.g. `gem "puma"` — to your Gemfile. ' \
+              "(#{e.message})"
+      end
 
-        launcher = Puma::Launcher.new(puma_config)
+      # Loads the gems the HTTP transport needs. They are optional
+      # dependencies — deliberately NOT in the gemspec, so consumers that
+      # only use the models/storage API (or the stdio transport) don't
+      # carry HTTP machinery. The Rack *server* is the host application's
+      # choice: any bundled server registered with Rackup will do.
+      def require_http_transport_gems
+        require "rack"
+        require "rackup"
+      rescue LoadError => e
+        raise LoadError,
+              "TrakFlow's MCP HTTP transport needs the optional rackup gem plus a Rack " \
+              'server that supports rack.hijack. Add `gem "rackup"` — and `gem "puma"` ' \
+              "if your app doesn't already bundle a server — to your Gemfile. (#{e.message})"
+      end
 
-        trap("INT") { launcher.stop }
-        trap("TERM") { launcher.stop }
+      private
 
-        launcher.run
+      def start_http_server(port, handler_name = nil)
+        http_handler(handler_name).run(rack_app, Host: "0.0.0.0", Port: port)
       end
 
+      # Every tool the MCP server exposes, grouped by concern.
+      TOOLS = [
+        # Task management
+        Tools::TaskCreate, Tools::TaskUpdate, Tools::TaskClose,
+        Tools::TaskStart, Tools::TaskBlock, Tools::TaskDefer,
+        # Plan/Workflow
+        Tools::PlanCreate, Tools::PlanAddStep, Tools::PlanStart,
+        Tools::PlanRun, Tools::WorkflowDiscard, Tools::WorkflowSummarize,
+        # Dependencies
+        Tools::DepAdd, Tools::DepRemove,
+        # Labels
+        Tools::LabelAdd, Tools::LabelRemove,
+        # Comments
+        Tools::CommentAdd
+      ].freeze
+
+      RESOURCES = [
+        Resources::TaskList, Resources::TaskById, Resources::TaskNext,
+        Resources::PlanList, Resources::PlanById,
+        Resources::WorkflowList, Resources::WorkflowById,
+        Resources::LabelList, Resources::DependencyGraph
+      ].freeze
+
+      private_constant :TOOLS, :RESOURCES
+
       def register_tools
-        # Task management tools
-        mcp_server.register_tool(Tools::TaskCreate)
-        mcp_server.register_tool(Tools::TaskUpdate)
-        mcp_server.register_tool(Tools::TaskClose)
-        mcp_server.register_tool(Tools::TaskStart)
-        mcp_server.register_tool(Tools::TaskBlock)
-        mcp_server.register_tool(Tools::TaskDefer)
-
-        # Plan/Workflow tools
-        mcp_server.register_tool(Tools::PlanCreate)
-        mcp_server.register_tool(Tools::PlanAddStep)
-        mcp_server.register_tool(Tools::PlanStart)
-        mcp_server.register_tool(Tools::PlanRun)
-        mcp_server.register_tool(Tools::WorkflowDiscard)
-        mcp_server.register_tool(Tools::WorkflowSummarize)
-
-        # Dependency tools
-        mcp_server.register_tool(Tools::DepAdd)
-        mcp_server.register_tool(Tools::DepRemove)
-
-        # Label tools
-        mcp_server.register_tool(Tools::LabelAdd)
-        mcp_server.register_tool(Tools::LabelRemove)
-
-        # Comment tool
-        mcp_server.register_tool(Tools::CommentAdd)
+        TOOLS.each { |tool| mcp_server.register_tool(tool) }
       end
 
       def register_resources
-        mcp_server.register_resource(Resources::TaskList)
-        mcp_server.register_resource(Resources::TaskById)
-        mcp_server.register_resource(Resources::TaskNext)
-        mcp_server.register_resource(Resources::PlanList)
-        mcp_server.register_resource(Resources::PlanById)
-        mcp_server.register_resource(Resources::WorkflowList)
-        mcp_server.register_resource(Resources::WorkflowById)
-        mcp_server.register_resource(Resources::LabelList)
-        mcp_server.register_resource(Resources::DependencyGraph)
+        RESOURCES.each { |resource| mcp_server.register_resource(resource) }
       end
     end
   end

data/lib/trak_flow/mcp/tools/task_create.rb

@@ -20,23 +20,23 @@ module TrakFlow
         def call(title:, type: "task", priority: 2, description: nil, assignee: nil, parent_id: nil, labels: [])
           self.class.with_database do |db|
             task = if parent_id
-                db.create_child_task(parent_id, {
-                  title: title,
-                  description: description,
-                  type: type,
-                  priority: priority,
-                  assignee: assignee
-                })
-              else
-                new_task = Models::Task.new(
-                  title: title,
-                  description: description,
-                  type: type,
-                  priority: priority,
-                  assignee: assignee
-                )
-                db.create_task(new_task)
-              end
+                     db.create_child_task(parent_id, {
+                       title: title,
+                       description: description,
+                       type: type,
+                       priority: priority,
+                       assignee: assignee
+                     })
+                   else
+                     new_task = Models::Task.new(
+                       title: title,
+                       description: description,
+                       type: type,
+                       priority: priority,
+                       assignee: assignee
+                     )
+                     db.create_task(new_task)
+                   end
 
             labels.each do |label_name|
               db.add_label(Models::Label.new(task_id: task.id, name: label_name))

data/lib/trak_flow/models/task.rb

@@ -20,23 +20,27 @@ module TrakFlow
       VALID_PRIORITIES = TrakFlow::PRIORITIES
       VALID_TYPES = TrakFlow::TYPES
 
+      # Attributes that default to nil when not given.
+      NILABLE_ATTRIBUTES = %i[id title assignee parent_id closed_at content_hash source_plan_id].freeze
+
+      # Attributes with a non-nil default.
+      ATTRIBUTE_DEFAULTS = {
+        description: "",
+        status: "open",
+        priority: 2,
+        type: "task",
+        plan: false,
+        ephemeral: false,
+        notes: ""
+      }.freeze
+
       def initialize(attrs = {})
-        @id = attrs[:id]
-        @title = attrs[:title]
-        @description = attrs[:description] || ""
-        @status = attrs[:status] || "open"
-        @priority = attrs[:priority] || 2
-        @type = attrs[:type] || "task"
-        @assignee = attrs[:assignee]
-        @parent_id = attrs[:parent_id]
-        @created_at = attrs[:created_at] || Time.now.utc
-        @updated_at = attrs[:updated_at] || Time.now.utc
-        @closed_at = attrs[:closed_at]
-        @content_hash = attrs[:content_hash]
-        @plan = attrs[:plan] || false
-        @source_plan_id = attrs[:source_plan_id]
-        @ephemeral = attrs[:ephemeral] || false
-        @notes = attrs[:notes] || ""
+        NILABLE_ATTRIBUTES.each { |key| instance_variable_set("@#{key}", attrs[key]) }
+        ATTRIBUTE_DEFAULTS.each { |key, default| instance_variable_set("@#{key}", attrs[key] || default) }
+
+        now = Time.now.utc
+        @created_at = attrs[:created_at] || now
+        @updated_at = attrs[:updated_at] || now
       end
 
       def valid?
@@ -64,7 +68,7 @@ module TrakFlow
       end
 
       def closed?
-        status == "closed" || status == "tombstone"
+        %w[closed tombstone].include?(status)
       end
 
       def in_progress?

data/lib/trak_flow/storage/database.rb

@@ -141,13 +141,13 @@ module TrakFlow
       def find_dependencies(issue_id, direction: :both)
         deps = []
 
-        if direction == :both || direction == :outgoing
+        if %i[both outgoing].include?(direction)
           @db[:dependencies].where(source_id: issue_id).each do |row|
             deps << Models::Dependency.from_hash(row)
           end
         end
 
-        if direction == :both || direction == :incoming
+        if %i[both incoming].include?(direction)
           @db[:dependencies].where(target_id: issue_id).each do |row|
             deps << Models::Dependency.from_hash(row)
           end
@@ -272,7 +272,7 @@ module TrakFlow
       end
 
       def create_child_task(parent_id, attrs)
-        parent = find_task!(parent_id)
+        find_task!(parent_id)
         child_count = @db[:tasks].where(parent_id: parent_id).count
         child_id = IdGenerator.generate_child_id(parent_id, child_count + 1)
 
@@ -373,6 +373,15 @@ module TrakFlow
       private
 
       def setup_schema
+        create_tasks_table
+        migrate_schema_if_needed!
+        create_dependencies_table
+        create_labels_table
+        create_comments_table
+        create_blocked_tasks_table
+      end
+
+      def create_tasks_table
         @db.create_table?(:tasks) do
           String :id, primary_key: true
           String :title, null: false
@@ -400,9 +409,9 @@ module TrakFlow
           index :source_plan_id
           index :ephemeral
         end
+      end
 
-        migrate_schema_if_needed!
-
+      def create_dependencies_table
         @db.create_table?(:dependencies) do
           String :id, primary_key: true
           String :source_id, null: false
@@ -414,7 +423,9 @@ module TrakFlow
           index :target_id
           index :type
         end
+      end
 
+      def create_labels_table
         @db.create_table?(:labels) do
           String :id, primary_key: true
           String :task_id, null: false
@@ -425,7 +436,9 @@ module TrakFlow
           index :name
           unique %i[task_id name]
         end
+      end
 
+      def create_comments_table
         @db.create_table?(:comments) do
           String :id, primary_key: true
           String :task_id, null: false
@@ -436,7 +449,9 @@ module TrakFlow
 
           index :task_id
         end
+      end
 
+      def create_blocked_tasks_table
         @db.create_table?(:blocked_tasks) do
           String :task_id, primary_key: true
 
@@ -498,11 +513,7 @@ module TrakFlow
       def apply_status_filter(dataset, status)
         return dataset unless status
 
-        if status.is_a?(Array)
-          dataset.where(status: status)
-        else
-          dataset.where(status: status)
-        end
+        dataset.where(status: status)
       end
 
       def apply_priority_filter(dataset, filters)
@@ -601,8 +612,8 @@ module TrakFlow
 
         visited << task_id
         blocking_deps = @db[:dependencies]
-          .where(target_id: task_id)
-          .where(type: Models::Dependency::BLOCKING_TYPES)
+                        .where(target_id: task_id)
+                        .where(type: Models::Dependency::BLOCKING_TYPES)
 
         blocking_deps.any? { |dep| blocker_active?(dep, visited) }
       end
@@ -628,10 +639,9 @@ module TrakFlow
           @db.alter_table(:tasks) { add_column :source_plan_id, String } rescue nil
           @db.add_index :tasks, :source_plan_id rescue nil
         end
-        unless columns.include?(:ephemeral)
-          @db.alter_table(:tasks) { add_column :ephemeral, TrueClass, default: false } rescue nil
-          @db.add_index :tasks, :ephemeral rescue nil
-        end
+        return if columns.include?(:ephemeral)
+        @db.alter_table(:tasks) { add_column :ephemeral, TrueClass, default: false } rescue nil
+        @db.add_index :tasks, :ephemeral rescue nil
       end
     end
   end