trak_flow 0.1.3

data/lib/trak_flow/storage/jsonl.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+module TrakFlow
+  module Storage
+    # JSONL (JSON Lines) persistence layer for Git integration
+    # This is the git-tracked source of truth stored in .trak_flow/tasks.jsonl
+    # One JSON entity per line makes diffs readable and merges usually automatic
+    class Jsonl
+      ENTITY_TYPES = %w[task dependency label comment].freeze
+
+      attr_reader :path
+
+      def initialize(path = nil)
+        @path = path || TrakFlow.jsonl_path
+      end
+
+      # Export all data from database to JSONL file
+      # - Plans are exported (persistent blueprints)
+      # - Ephemeral Workflows are NOT exported (temporary only)
+      def export(db)
+        entities = []
+
+        # Export regular tasks (excluding ephemeral) and include Plans
+        db.list_tasks(include_ephemeral: false, include_plans: true, include_tombstones: true).each do |task|
+          entities << { type: "task", data: task.to_h }
+        end
+
+        db.all_task_ids.each do |task_id|
+          db.find_dependencies(task_id, direction: :outgoing).each do |dep|
+            entities << { type: "dependency", data: dep.to_h }
+          end
+
+          db.find_labels(task_id).each do |label|
+            entities << { type: "label", data: label.to_h }
+          end
+
+          db.find_comments(task_id).each do |comment|
+            entities << { type: "comment", data: comment.to_h }
+          end
+        end
+
+        write_entities(entities)
+        db.mark_clean!
+      end
+
+      # Import all data from JSONL file to database
+      # @param db [Database] the database to import into
+      # @param orphan_handling [String] how to handle orphaned tasks
+      # @param error_policy [String] how to handle import errors: "warn", "strict", or "ignore"
+      def import(db, orphan_handling: nil, error_policy: nil)
+        orphan_handling ||= TrakFlow.config.get("import.orphan_handling")
+        error_policy ||= TrakFlow.config.get("import.error_policy") || "warn"
+
+        entities = read_entities
+        tasks = []
+        dependencies = []
+        labels = []
+        comments = []
+        import_errors = []
+
+        entities.each do |entity|
+          case entity[:type]
+          when "task"
+            tasks << Models::Task.from_hash(entity[:data])
+          when "dependency"
+            dependencies << Models::Dependency.from_hash(entity[:data])
+          when "label"
+            labels << Models::Label.from_hash(entity[:data])
+          when "comment"
+            comments << Models::Comment.from_hash(entity[:data])
+          end
+        end
+
+        tasks = handle_orphans(tasks, orphan_handling)
+
+        db.import_tasks(tasks)
+
+        import_errors += import_entities(db, :add_dependency, dependencies, error_policy)
+        import_errors += import_entities(db, :add_label, labels, error_policy)
+        import_errors += import_entities(db, :add_comment, comments, error_policy)
+
+        raise_if_strict_errors(import_errors, error_policy)
+      end
+
+      private
+
+      def import_entities(db, method, entities, error_policy)
+        errors = []
+        entities.each do |entity|
+          db.send(method, entity)
+        rescue Error => e
+          error_info = { entity_type: entity.class.name, error: e.message }
+          errors << error_info
+          handle_import_error(error_info, error_policy)
+        end
+        errors
+      end
+
+      def handle_import_error(error_info, policy)
+        case policy
+        when "strict"
+          # Errors collected for batch raise
+        when "warn"
+          debug_me "Warning: Import failed for #{error_info[:entity_type]}: #{error_info[:error]}"
+        when "ignore"
+          # Silent
+        end
+      end
+
+      def raise_if_strict_errors(errors, policy)
+        return if errors.empty? || policy != "strict"
+
+        messages = errors.map { |e| "#{e[:entity_type]}: #{e[:error]}" }
+        raise ValidationError, "Import failed with #{errors.size} error(s):\n  #{messages.join("\n  ")}"
+      end
+
+      public
+
+      # Check if JSONL file has changed since last import
+      def changed_since?(timestamp)
+        return true unless File.exist?(path)
+
+        File.mtime(path) > timestamp
+      end
+
+      # Get content hash of the JSONL file
+      def content_hash
+        return nil unless File.exist?(path)
+
+        Digest::SHA256.hexdigest(File.read(path))[0, 16]
+      end
+
+      # Check if file exists
+      def exists?
+        File.exist?(path)
+      end
+
+      # Read raw entities from file
+      def read_entities
+        return [] unless File.exist?(path)
+
+        entities = []
+        File.readlines(path).each_with_index do |line, index|
+          line = line.strip
+          next if line.empty? || line.start_with?("#")
+
+          begin
+            data = Oj.load(line, mode: :compat, symbol_keys: true)
+            entities << data if valid_entity?(data)
+          rescue Oj::ParseError => e
+            debug_me "Warning: Could not parse line #{index + 1}: #{e.message}"
+          end
+        end
+
+        entities
+      end
+
+      # Write entities to file
+      def write_entities(entities)
+        FileUtils.mkdir_p(File.dirname(path))
+
+        File.open(path, "w") do |f|
+          f.puts "# TrakFlow task tracker data"
+          f.puts "# Generated at #{Time.now.utc.iso8601}"
+          f.puts ""
+
+          entities.each do |entity|
+            f.puts Oj.dump(entity, mode: :compat)
+          end
+        end
+      end
+
+      # Incremental export - only export changed entities
+      def incremental_export(db, changed_ids)
+        return export(db) unless File.exist?(path)
+
+        existing = read_entities
+        existing_by_id = {}
+
+        existing.each do |entity|
+          id = entity.dig(:data, :id)
+          existing_by_id["#{entity[:type]}-#{id}"] = entity if id
+        end
+
+        changed_ids.each do |task_id|
+          task = db.find_task(task_id)
+          if task
+            key = "task-#{task_id}"
+            existing_by_id[key] = { type: "task", data: task.to_h }
+
+            db.find_dependencies(task_id, direction: :outgoing).each do |dep|
+              dep_key = "dependency-#{dep.id}"
+              existing_by_id[dep_key] = { type: "dependency", data: dep.to_h }
+            end
+
+            db.find_labels(task_id).each do |label|
+              label_key = "label-#{label.id}"
+              existing_by_id[label_key] = { type: "label", data: label.to_h }
+            end
+
+            db.find_comments(task_id).each do |comment|
+              comment_key = "comment-#{comment.id}"
+              existing_by_id[comment_key] = { type: "comment", data: comment.to_h }
+            end
+          else
+            existing_by_id.delete("task-#{task_id}")
+          end
+        end
+
+        write_entities(existing_by_id.values)
+        db.mark_clean!
+      end
+
+      private
+
+      def valid_entity?(data)
+        return false unless data.is_a?(Hash)
+        return false unless ENTITY_TYPES.include?(data[:type])
+        return false unless data[:data].is_a?(Hash)
+
+        true
+      end
+
+      def handle_orphans(tasks, handling)
+        task_ids = Set.new(tasks.map(&:id))
+        orphans = []
+        valid = []
+
+        tasks.each do |task|
+          if task.parent_id && !task_ids.include?(task.parent_id)
+            orphans << task
+          else
+            valid << task
+          end
+        end
+
+        return valid if orphans.empty?
+
+        case handling
+        when "allow"
+          valid + orphans
+        when "skip"
+          debug_me "Skipping #{orphans.size} orphaned tasks"
+          valid
+        when "resurrect"
+          orphans.each do |orphan|
+            debug_me "Resurrecting orphan: #{orphan.id} (parent: #{orphan.parent_id})"
+            orphan.parent_id = nil
+          end
+          valid + orphans
+        when "strict"
+          raise ValidationError, "Found #{orphans.size} orphaned tasks with missing parents"
+        else
+          valid + orphans
+        end
+      end
+    end
+  end
+end

data/lib/trak_flow/time_parser.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module TrakFlow
+  # Shared time parsing utilities for model deserialization
+  module TimeParser
+    def self.parse(value)
+      return nil if value.nil?
+      return value if value.is_a?(Time)
+
+      Time.parse(value)
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/lib/trak_flow/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module TrakFlow
+  VERSION = '0.1.3'
+end

data/lib/trak_flow.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "json"
+require "securerandom"
+require "set"
+require "time"
+
+require "oj"
+require "sequel"
+require "sqlite3"
+require "thor"
+require "pastel"
+require "tty-table"
+require "debug_me"
+require "anyway_config"
+
+module TrakFlow
+  class Error < StandardError; end
+  class NotInitializedError < Error; end
+  class TaskNotFoundError < Error; end
+  class DependencyCycleError < Error; end
+  class ValidationError < Error; end
+  class ConfigurationError < Error; end
+
+  TRAK_FLOW_DIR = ".trak_flow"
+  DATABASE_FILE = "trak_flow.db"
+  JSONL_FILE = "tasks.jsonl"  # Default, can be overridden via config.storage.jsonl_file
+  CONFIG_FILE = "config.yml"
+
+  STATUSES = %w[open in_progress blocked deferred closed tombstone pinned].freeze
+  PRIORITIES = (0..4).to_a.freeze
+  TYPES = %w[bug feature task epic chore].freeze
+  DEPENDENCY_TYPES = %w[blocks related parent-child discovered-from].freeze
+
+  class << self
+    def root
+      @root ||= find_root
+    end
+
+    def trak_flow_dir
+      File.join(root, TRAK_FLOW_DIR)
+    end
+
+    def database_path
+      path = config.database.path
+      File.expand_path(path)
+    end
+
+    def jsonl_path
+      jsonl_file = config.storage.jsonl_file rescue JSONL_FILE
+      File.join(trak_flow_dir, jsonl_file)
+    end
+
+    def config_path
+      File.join(trak_flow_dir, CONFIG_FILE)
+    end
+
+    def initialized?
+      File.directory?(trak_flow_dir) && File.exist?(database_path)
+    end
+
+    def ensure_initialized!
+      raise NotInitializedError, "TrakFlow not initialized. Run 'tf init' first." unless initialized?
+    end
+
+    def reset_root!
+      @root = nil
+    end
+
+    private
+
+    def find_root(start_dir = Dir.pwd)
+      dir = start_dir
+      loop do
+        trak_flow_path = File.join(dir, TRAK_FLOW_DIR)
+        return dir if File.directory?(trak_flow_path)
+
+        parent = File.dirname(dir)
+        return start_dir if parent == dir
+
+        dir = parent
+      end
+    end
+  end
+end
+
+require_relative "trak_flow/version"
+require_relative "trak_flow/id_generator"
+require_relative "trak_flow/time_parser"
+require_relative "trak_flow/config"
+require_relative "trak_flow/models/task"
+require_relative "trak_flow/models/dependency"
+require_relative "trak_flow/models/label"
+require_relative "trak_flow/models/comment"
+require_relative "trak_flow/storage/database"
+require_relative "trak_flow/storage/jsonl"
+require_relative "trak_flow/graph/dependency_graph"
+require_relative "trak_flow/cli"

data/mkdocs.yml

@@ -0,0 +1,143 @@
+site_name: TrakFlow Documentation
+site_description: "A distributed task tracking system for AI agents with DAG-based workflow engine"
+site_author: "Dewayne VanHoozer"
+site_url: "https://madbomber.github.io/trak_flow/"
+
+repo_name: "MadBomber/trak_flow"
+repo_url: "https://github.com/MadBomber/trak_flow"
+edit_uri: "edit/main/docs/"
+
+theme:
+  name: material
+  language: en
+  favicon: assets/logo.png
+
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: teal
+      accent: deep-orange
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: teal
+      accent: deep-orange
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+  font:
+    text: Roboto
+    code: Roboto Mono
+
+  features:
+    - navigation.instant
+    - navigation.tracking
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.sections
+    - navigation.path
+    - navigation.indexes
+    - navigation.top
+    - toc.follow
+    - search.suggest
+    - search.highlight
+    - search.share
+    - header.autohide
+    - content.code.copy
+    - content.code.annotate
+    - content.tabs.link
+    - content.tooltips
+    - content.action.edit
+    - content.action.view
+
+plugins:
+  - search:
+      separator: '[\s\-,:!=\[\]()"\`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
+
+markdown_extensions:
+  - abbr
+  - admonition
+  - attr_list
+  - def_list
+  - footnotes
+  - md_in_html
+  - toc:
+      permalink: true
+      title: On this page
+  - pymdownx.arithmatex:
+      generic: true
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.caret
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.keys
+  - pymdownx.magiclink:
+      repo_url_shorthand: true
+      user: MadBomber
+      repo: trak_flow
+  - pymdownx.mark
+  - pymdownx.smartsymbols
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tilde
+
+extra_css:
+  - assets/stylesheets/extra.css
+
+extra:
+  version: 0.0.1
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/MadBomber/trak_flow
+      name: GitHub Repository
+  generator: false
+
+nav:
+  - Home: index.md
+  - Getting Started:
+    - Installation: getting-started/installation.md
+    - Quick Start: getting-started/quick-start.md
+    - Configuration: getting-started/configuration.md
+  - Core Concepts:
+    - Overview: core-concepts/overview.md
+    - Tasks: core-concepts/tasks.md
+    - Plans & Workflows: core-concepts/plans-workflows.md
+    - Dependencies: core-concepts/dependencies.md
+    - Labels: core-concepts/labels.md
+  - CLI Reference:
+    - Overview: cli/overview.md
+    - Task Commands: cli/task-commands.md
+    - Plan & Workflow Commands: cli/plan-commands.md
+    - Dependency Commands: cli/dependency-commands.md
+    - Label Commands: cli/label-commands.md
+    - Admin Commands: cli/admin-commands.md
+  - MCP Server:
+    - Overview: mcp/overview.md
+    - Tools Reference: mcp/tools.md
+    - Resources Reference: mcp/resources.md
+    - Integration Guide: mcp/integration.md
+  - API Reference:
+    - Ruby Library: api/ruby-library.md
+    - Task Model: api/task-model.md
+    - Database: api/database.md
+
+copyright: Copyright © 2025 Dewayne VanHoozer