trak_flow 0.1.3

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module TrakFlow
+  module Mcp
+    module Tools
+      class TaskUpdate < BaseTool
+        tool_name "task_update"
+        description "Update task attributes (title, priority, status, description, assignee)"
+
+        arguments do
+          required(:id).filled(:string).description("Task ID to update")
+          optional(:title).filled(:string).description("New title")
+          optional(:status).filled(:string).description("New status: open, in_progress, blocked, deferred, closed")
+          optional(:priority).filled(:integer).description("New priority 0-4")
+          optional(:description).filled(:string).description("New description")
+          optional(:assignee).filled(:string).description("New assignee")
+        end
+
+        def call(id:, title: nil, status: nil, priority: nil, description: nil, assignee: nil)
+          self.class.with_database do |db|
+            task = db.find_task!(id)
+
+            task.title = title if title
+            task.status = status if status
+            task.priority = priority if priority
+            task.description = description if description
+            task.assignee = assignee if assignee
+
+            db.update_task(task)
+            task.to_h
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module TrakFlow
+  module Mcp
+    module Tools
+      class WorkflowDiscard < BaseTool
+        tool_name "workflow_discard"
+        description "Discard an ephemeral Workflow (deletes it and all its tasks)"
+
+        arguments do
+          required(:id).filled(:string).description("Workflow ID to discard")
+        end
+
+        def call(id:)
+          self.class.with_database do |db|
+            workflow = db.find_task!(id)
+            raise TrakFlow::Error, "Can only discard ephemeral Workflows" unless workflow.discardable?
+
+            db.child_tasks(id).each { |child| db.delete_task(child.id) }
+            db.delete_task(id)
+
+            { discarded: id, success: true }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module TrakFlow
+  module Mcp
+    module Tools
+      class WorkflowSummarize < BaseTool
+        tool_name "workflow_summarize"
+        description "Summarize and close a Workflow"
+
+        arguments do
+          required(:id).filled(:string).description("Workflow ID to summarize")
+          required(:summary).filled(:string).description("Summary text")
+        end
+
+        def call(id:, summary:)
+          self.class.with_database do |db|
+            workflow = db.find_task!(id)
+
+            workflow.notes = "#{workflow.notes}\n\n[Summary]\n#{summary}".strip
+            workflow.close!(reason: "summarized")
+            db.update_task(workflow)
+
+            db.child_tasks(id).each do |child|
+              child.close!(reason: "workflow summarized")
+              db.update_task(child)
+            end
+
+            workflow.to_h
+          end
+        end
+      end
+    end
+  end
+end

data/lib/trak_flow/mcp.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "fast_mcp"
+
+# Tools
+require_relative "mcp/tools/base_tool"
+require_relative "mcp/tools/task_create"
+require_relative "mcp/tools/task_update"
+require_relative "mcp/tools/task_close"
+require_relative "mcp/tools/task_start"
+require_relative "mcp/tools/task_block"
+require_relative "mcp/tools/task_defer"
+require_relative "mcp/tools/plan_create"
+require_relative "mcp/tools/plan_add_step"
+require_relative "mcp/tools/plan_start"
+require_relative "mcp/tools/plan_run"
+require_relative "mcp/tools/workflow_discard"
+require_relative "mcp/tools/workflow_summarize"
+require_relative "mcp/tools/dep_add"
+require_relative "mcp/tools/dep_remove"
+require_relative "mcp/tools/label_add"
+require_relative "mcp/tools/label_remove"
+require_relative "mcp/tools/comment_add"
+
+# Resources
+require_relative "mcp/resources/base_resource"
+require_relative "mcp/resources/task_list"
+require_relative "mcp/resources/task_by_id"
+require_relative "mcp/resources/task_next"
+require_relative "mcp/resources/plan_list"
+require_relative "mcp/resources/plan_by_id"
+require_relative "mcp/resources/workflow_list"
+require_relative "mcp/resources/workflow_by_id"
+require_relative "mcp/resources/label_list"
+require_relative "mcp/resources/dependency_graph"
+
+# Server
+require_relative "mcp/server"

data/lib/trak_flow/models/comment.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module TrakFlow
+  module Models
+    # Represents a comment on a task
+    class Comment
+      attr_accessor :id, :task_id, :author, :body, :created_at, :updated_at
+
+      def initialize(attrs = {})
+        @id = attrs[:id] || SecureRandom.uuid
+        @task_id = attrs[:task_id]
+        @author = attrs[:author] || TrakFlow.config.get("actor")
+        @body = attrs[:body]
+        @created_at = attrs[:created_at] || Time.now.utc
+        @updated_at = attrs[:updated_at] || Time.now.utc
+      end
+
+      def valid?
+        errors.empty?
+      end
+
+      def errors
+        errs = []
+        errs << "Task ID is required" if task_id.nil? || task_id.to_s.strip.empty?
+        errs << "Body is required" if body.nil? || body.strip.empty?
+        errs
+      end
+
+      def validate!
+        raise ValidationError, errors.join(", ") unless valid?
+      end
+
+      def touch!
+        self.updated_at = Time.now.utc
+      end
+
+      def to_h
+        {
+          id: id,
+          task_id: task_id,
+          author: author,
+          body: body,
+          created_at: created_at&.iso8601,
+          updated_at: updated_at&.iso8601
+        }.compact
+      end
+
+      def to_json(*args)
+        Oj.dump(to_h, mode: :compat)
+      end
+
+      class << self
+        def from_hash(hash)
+          hash = hash.transform_keys(&:to_sym)
+          new(
+            id: hash[:id],
+            task_id: hash[:task_id],
+            author: hash[:author],
+            body: hash[:body],
+            created_at: TimeParser.parse(hash[:created_at]),
+            updated_at: TimeParser.parse(hash[:updated_at])
+          )
+        end
+
+        def from_json(json_string)
+          from_hash(Oj.load(json_string, mode: :compat, symbol_keys: true))
+        end
+      end
+    end
+  end
+end

data/lib/trak_flow/models/dependency.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module TrakFlow
+  module Models
+    # Represents a dependency relationship between two issues
+    # Types:
+    #   - blocks: Hard dependency - target cannot proceed until source is closed
+    #   - related: Soft link - informational only
+    #   - parent-child: Hierarchical relationship
+    #   - discovered-from: Traceability link to origin
+    class Dependency
+      attr_accessor :id, :source_id, :target_id, :type, :created_at
+
+      VALID_TYPES = TrakFlow::DEPENDENCY_TYPES
+
+      # Blocking dependency types affect ready-work calculations
+      BLOCKING_TYPES = %w[blocks parent-child].freeze
+
+      def initialize(attrs = {})
+        @id = attrs[:id] || SecureRandom.uuid
+        @source_id = attrs[:source_id]
+        @target_id = attrs[:target_id]
+        @type = attrs[:type] || "blocks"
+        @created_at = attrs[:created_at] || Time.now.utc
+      end
+
+      def valid?
+        errors.empty?
+      end
+
+      def errors
+        errs = []
+        errs << "Source ID is required" if source_id.nil? || source_id.strip.empty?
+        errs << "Target ID is required" if target_id.nil? || target_id.strip.empty?
+        errs << "Invalid type: #{type}" unless VALID_TYPES.include?(type)
+        errs << "Self-referential dependency not allowed" if source_id == target_id
+        errs
+      end
+
+      def validate!
+        raise ValidationError, errors.join(", ") unless valid?
+      end
+
+      def blocking?
+        BLOCKING_TYPES.include?(type)
+      end
+
+      def blocks?
+        type == "blocks"
+      end
+
+      def parent_child?
+        type == "parent-child"
+      end
+
+      def related?
+        type == "related"
+      end
+
+      def discovered_from?
+        type == "discovered-from"
+      end
+
+      def to_h
+        {
+          id: id,
+          source_id: source_id,
+          target_id: target_id,
+          type: type,
+          created_at: created_at&.iso8601
+        }.compact
+      end
+
+      def to_json(*args)
+        Oj.dump(to_h, mode: :compat)
+      end
+
+      class << self
+        def from_hash(hash)
+          hash = hash.transform_keys(&:to_sym)
+          new(
+            id: hash[:id],
+            source_id: hash[:source_id],
+            target_id: hash[:target_id],
+            type: hash[:type],
+            created_at: TimeParser.parse(hash[:created_at])
+          )
+        end
+
+        def from_json(json_string)
+          from_hash(Oj.load(json_string, mode: :compat, symbol_keys: true))
+        end
+      end
+    end
+  end
+end

data/lib/trak_flow/models/label.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module TrakFlow
+  module Models
+    # Represents a label attached to a task
+    # Labels provide flexible, multi-dimensional categorization beyond
+    # structured fields like status, priority, and type
+    class Label
+      attr_accessor :id, :task_id, :name, :created_at
+
+      def initialize(attrs = {})
+        @id = attrs[:id] || SecureRandom.uuid
+        @task_id = attrs[:task_id]
+        @name = attrs[:name]
+        @created_at = attrs[:created_at] || Time.now.utc
+      end
+
+      def valid?
+        errors.empty?
+      end
+
+      def errors
+        errs = []
+        errs << "Task ID is required" if task_id.nil? || task_id.to_s.strip.empty?
+        errs << "Name is required" if name.nil? || name.strip.empty?
+        errs << "Invalid label name" unless valid_name?
+        errs
+      end
+
+      def validate!
+        raise ValidationError, errors.join(", ") unless valid?
+      end
+
+      # Labels can use dimension:value format for state caching
+      def dimension
+        return nil unless name&.include?(":")
+
+        name.split(":").first
+      end
+
+      def value
+        return name unless name&.include?(":")
+
+        name.split(":", 2).last
+      end
+
+      def state_label?
+        name&.include?(":")
+      end
+
+      def to_h
+        {
+          id: id,
+          task_id: task_id,
+          name: name,
+          created_at: created_at&.iso8601
+        }.compact
+      end
+
+      def to_json(*args)
+        Oj.dump(to_h, mode: :compat)
+      end
+
+      class << self
+        def from_hash(hash)
+          hash = hash.transform_keys(&:to_sym)
+          new(
+            id: hash[:id],
+            task_id: hash[:task_id],
+            name: hash[:name],
+            created_at: TimeParser.parse(hash[:created_at])
+          )
+        end
+
+        def from_json(json_string)
+          from_hash(Oj.load(json_string, mode: :compat, symbol_keys: true))
+        end
+      end
+
+      private
+
+      def valid_name?
+        return false if name.nil?
+
+        # Allow alphanumeric, hyphens, underscores, and colons (for state labels)
+        name.match?(/^[a-zA-Z0-9_:-]+$/)
+      end
+    end
+  end
+end

data/lib/trak_flow/models/task.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module TrakFlow
+  module Models
+    # Represents a task in the TrakFlow system
+    #
+    # Tasks serve multiple roles determined by flags:
+    # - Plan (blueprint):  task.plan? == true
+    # - Workflow:          task.source_plan_id.present? && !task.plan?
+    # - Step (conceptual): child Task of a Plan
+    # - Work item:         child Task of a Workflow
+    #
+    # Tasks can be bugs, features, tasks, epics, or chores
+    class Task
+      attr_accessor :id, :title, :description, :status, :priority, :type,
+                    :assignee, :parent_id, :created_at, :updated_at, :closed_at,
+                    :content_hash, :plan, :source_plan_id, :ephemeral, :notes
+
+      VALID_STATUSES = TrakFlow::STATUSES
+      VALID_PRIORITIES = TrakFlow::PRIORITIES
+      VALID_TYPES = TrakFlow::TYPES
+
+      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] || ""
+      end
+
+      def valid?
+        errors.empty?
+      end
+
+      def errors
+        errs = []
+        errs << "Title is required" if title.nil? || title.strip.empty?
+        errs << "Invalid status: #{status}" unless VALID_STATUSES.include?(status)
+        errs << "Invalid priority: #{priority}" unless VALID_PRIORITIES.include?(priority)
+        errs << "Invalid type: #{type}" unless VALID_TYPES.include?(type)
+        errs << "Plans cannot be ephemeral" if plan && ephemeral
+        errs << "Plans cannot change status" if plan && status != "open"
+        errs << "Plans cannot be derived from other Plans" if plan && source_plan_id
+        errs
+      end
+
+      def validate!
+        raise ValidationError, errors.join(", ") unless valid?
+      end
+
+      def open?
+        status == "open"
+      end
+
+      def closed?
+        status == "closed" || status == "tombstone"
+      end
+
+      def in_progress?
+        status == "in_progress"
+      end
+
+      def blocked?
+        status == "blocked"
+      end
+
+      def epic?
+        type == "epic"
+      end
+
+      # Plan/Workflow role predicates
+
+      def plan?
+        !!plan
+      end
+
+      def workflow?
+        source_plan_id && !source_plan_id.to_s.empty? && !plan?
+      end
+
+      def ephemeral?
+        !!ephemeral
+      end
+
+      def executable?
+        !plan?
+      end
+
+      def discardable?
+        ephemeral?
+      end
+
+      def close!(reason: nil)
+        self.status = "closed"
+        self.closed_at = Time.now.utc
+        self.notes = "#{notes}\n[Closed] #{reason}".strip if reason
+        touch!
+      end
+
+      def reopen!(reason: nil)
+        self.status = "open"
+        self.closed_at = nil
+        self.notes = "#{notes}\n[Reopened] #{reason}".strip if reason
+        touch!
+      end
+
+      def touch!
+        self.updated_at = Time.now.utc
+        update_content_hash!
+      end
+
+      def append_trace(action, message)
+        timestamp = Time.now.utc.iso8601
+        entry = "[#{timestamp}] [#{action}] #{message}"
+        self.notes = "#{notes}\n#{entry}".strip
+        touch!
+      end
+
+      def update_content_hash!
+        self.content_hash = IdGenerator.content_hash(to_h.except(:content_hash, :updated_at))
+      end
+
+      def to_h
+        {
+          id: id,
+          title: title,
+          description: description,
+          status: status,
+          priority: priority,
+          type: type,
+          assignee: assignee,
+          parent_id: parent_id,
+          created_at: created_at&.iso8601,
+          updated_at: updated_at&.iso8601,
+          closed_at: closed_at&.iso8601,
+          content_hash: content_hash,
+          plan: plan,
+          source_plan_id: source_plan_id,
+          ephemeral: ephemeral,
+          notes: notes
+        }.compact
+      end
+
+      def to_json(*args)
+        Oj.dump(to_h, mode: :compat)
+      end
+
+      class << self
+        def from_hash(hash)
+          hash = hash.transform_keys(&:to_sym)
+          new(
+            id: hash[:id],
+            title: hash[:title],
+            description: hash[:description],
+            status: hash[:status],
+            priority: hash[:priority]&.to_i,
+            type: hash[:type],
+            assignee: hash[:assignee],
+            parent_id: hash[:parent_id],
+            created_at: TimeParser.parse(hash[:created_at]),
+            updated_at: TimeParser.parse(hash[:updated_at]),
+            closed_at: TimeParser.parse(hash[:closed_at]),
+            content_hash: hash[:content_hash],
+            plan: hash[:plan],
+            source_plan_id: hash[:source_plan_id],
+            ephemeral: hash[:ephemeral],
+            notes: hash[:notes]
+          )
+        end
+
+        def from_json(json_string)
+          from_hash(Oj.load(json_string, mode: :compat, symbol_keys: true))
+        end
+      end
+    end
+  end
+end