trak_flow 0.1.3

data/examples/basic_usage.rb

@@ -0,0 +1,365 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# TrakFlow Basic Usage Demo
+#
+# This example demonstrates the core functionality of TrakFlow,
+# a distributed task tracking system designed for robots/AI agents.
+#
+# Run with: bundle exec ruby examples/basic_usage.rb
+
+require "bundler/setup"
+require "trak_flow"
+require "fileutils"
+require "tmpdir"
+
+# Create a temporary directory for the demo
+demo_dir = Dir.mktmpdir("trak_flow_demo")
+Dir.chdir(demo_dir)
+
+# Reset TrakFlow to use the demo directory
+TrakFlow.reset_root!
+TrakFlow.reset_config!
+
+puts <<~HEADER
+  ============================================================
+  TrakFlow Basic Usage Demo
+  ============================================================
+  Demo directory: #{demo_dir}
+
+HEADER
+
+# =============================================================================
+# 1. Initialize TrakFlow
+# =============================================================================
+
+puts "1. Initializing TrakFlow..."
+trak_flow_dir = File.join(demo_dir, ".trak_flow")
+FileUtils.mkdir_p(trak_flow_dir)
+
+db_path = File.join(trak_flow_dir, "trak_flow.db")
+db = TrakFlow::Storage::Database.new(db_path)
+db.connect
+puts "   Database initialized at #{db_path}\n\n"
+
+# =============================================================================
+# 2. Configuration
+# =============================================================================
+
+puts "2. Configuration..."
+puts "   Actor: #{TrakFlow.config.actor}"
+puts "   Output JSON: #{TrakFlow.config.output.json}"
+puts "   Daemon auto-start: #{TrakFlow.config.daemon.auto_start}"
+
+# Modify configuration
+TrakFlow.configure do |config|
+  config.actor = "demo-robot"
+end
+puts "   Actor (after configure): #{TrakFlow.config.actor}\n\n"
+
+# =============================================================================
+# 3. Creating Tasks
+# =============================================================================
+
+puts "3. Creating Tasks..."
+
+# Create an epic
+epic = TrakFlow::Models::Task.new(
+  title: "Build User Authentication System",
+  description: "Implement complete user auth with login, logout, and sessions",
+  type: "epic",
+  priority: 1
+)
+epic = db.create_task(epic)
+puts "   Created epic: [#{epic.id}] #{epic.title}"
+
+# Create regular tasks
+task1 = TrakFlow::Models::Task.new(
+  title: "Design database schema for users",
+  description: "Create tables for users, sessions, and password resets",
+  type: "task",
+  priority: 1,
+  assignee: "demo-robot"
+)
+task1 = db.create_task(task1)
+puts "   Created task: [#{task1.id}] #{task1.title}"
+
+task2 = TrakFlow::Models::Task.new(
+  title: "Implement login endpoint",
+  description: "POST /api/login with email and password",
+  type: "feature",
+  priority: 2
+)
+task2 = db.create_task(task2)
+puts "   Created feature: [#{task2.id}] #{task2.title}"
+
+task3 = TrakFlow::Models::Task.new(
+  title: "Write login integration tests",
+  type: "task",
+  priority: 3
+)
+task3 = db.create_task(task3)
+puts "   Created task: [#{task3.id}] #{task3.title}"
+
+# Create a bug
+bug = TrakFlow::Models::Task.new(
+  title: "Fix password validation regex",
+  description: "Current regex doesn't allow special characters",
+  type: "bug",
+  priority: 0  # Highest priority
+)
+bug = db.create_task(bug)
+puts "   Created bug: [#{bug.id}] #{bug.title}\n\n"
+
+# =============================================================================
+# 4. Dependencies
+# =============================================================================
+
+puts "4. Setting up Dependencies..."
+
+# Task2 (login endpoint) is blocked by Task1 (database schema)
+dep1 = TrakFlow::Models::Dependency.new(
+  source_id: task1.id,
+  target_id: task2.id,
+  type: "blocks"
+)
+db.add_dependency(dep1)
+puts "   #{task1.id} blocks #{task2.id}"
+
+# Task3 (tests) is blocked by Task2 (login endpoint)
+dep2 = TrakFlow::Models::Dependency.new(
+  source_id: task2.id,
+  target_id: task3.id,
+  type: "blocks"
+)
+db.add_dependency(dep2)
+puts "   #{task2.id} blocks #{task3.id}"
+
+# Epic is related to all tasks
+dep3 = TrakFlow::Models::Dependency.new(
+  source_id: epic.id,
+  target_id: task1.id,
+  type: "related"
+)
+db.add_dependency(dep3)
+puts "   #{epic.id} related to #{task1.id}\n\n"
+
+# =============================================================================
+# 5. Labels
+# =============================================================================
+
+puts "5. Adding Labels..."
+
+# Add labels to the bug
+label1 = TrakFlow::Models::Label.new(task_id: bug.id, name: "critical")
+db.add_label(label1)
+puts "   Added 'critical' label to #{bug.id}"
+
+label2 = TrakFlow::Models::Label.new(task_id: bug.id, name: "security")
+db.add_label(label2)
+puts "   Added 'security' label to #{bug.id}"
+
+# Use state labels (dimension:value format)
+db.set_state(task1.id, "complexity", "medium", reason: "Standard CRUD operations")
+puts "   Set complexity:medium on #{task1.id}"
+
+state = db.get_state(task1.id, "complexity")
+puts "   Retrieved state - complexity: #{state}\n\n"
+
+# =============================================================================
+# 6. Comments
+# =============================================================================
+
+puts "6. Adding Comments..."
+
+comment1 = TrakFlow::Models::Comment.new(
+  task_id: task1.id,
+  author: "demo-robot",
+  body: "Starting work on the users table schema."
+)
+db.add_comment(comment1)
+puts "   Added comment to #{task1.id}"
+
+comment2 = TrakFlow::Models::Comment.new(
+  task_id: task1.id,
+  author: "demo-robot",
+  body: "Schema draft complete. Ready for review."
+)
+db.add_comment(comment2)
+puts "   Added comment to #{task1.id}"
+
+comments = db.find_comments(task1.id)
+puts "   Task #{task1.id} has #{comments.size} comments\n\n"
+
+# =============================================================================
+# 7. Querying Tasks
+# =============================================================================
+
+puts "7. Querying Tasks..."
+
+# List all tasks
+all_tasks = db.list_tasks
+puts "   Total tasks: #{all_tasks.size}"
+
+# Filter by status
+open_tasks = db.list_tasks(status: "open")
+puts "   Open tasks: #{open_tasks.size}"
+
+# Filter by priority
+high_priority = db.list_tasks(priority: 0)
+puts "   P0 (highest priority) tasks: #{high_priority.size}"
+
+# Filter by type
+bugs = db.list_tasks(type: "bug")
+puts "   Bugs: #{bugs.size}"
+
+# Filter by assignee
+my_tasks = db.list_tasks(assignee: "demo-robot")
+puts "   Tasks assigned to demo-robot: #{my_tasks.size}\n\n"
+
+# =============================================================================
+# 8. Ready Work Detection
+# =============================================================================
+
+puts "8. Ready Work Detection..."
+
+ready = db.ready_tasks
+puts "   Tasks ready to work on (not blocked):"
+ready.each do |task|
+  puts "     [#{task.id}] P#{task.priority} #{task.type}: #{task.title}"
+end
+
+blocked = db.blocked_tasks
+puts "\n   Blocked tasks:"
+blocked.each do |task|
+  deps = db.blocking_dependencies(task.id)
+  blocker_ids = deps.map(&:source_id).join(", ")
+  puts "     [#{task.id}] #{task.title} (blocked by: #{blocker_ids})"
+end
+puts
+
+# =============================================================================
+# 9. Task Lifecycle
+# =============================================================================
+
+puts "9. Task Lifecycle..."
+
+# Start working on the bug (highest priority, not blocked)
+bug_fresh = db.find_task!(bug.id)
+bug_fresh.status = "in_progress"
+db.update_task(bug_fresh)
+puts "   Bug #{bug.id} status: #{bug_fresh.status}"
+
+# Complete the bug
+bug_fresh.close!(reason: "Fixed regex to allow !@#$%^&*()")
+db.update_task(bug_fresh)
+puts "   Bug #{bug.id} closed at: #{bug_fresh.closed_at}"
+
+# Complete task1 to unblock task2
+task1_fresh = db.find_task!(task1.id)
+task1_fresh.close!(reason: "Schema implemented and migrated")
+db.update_task(task1_fresh)
+puts "   Task #{task1.id} closed"
+
+# Check ready work again
+ready = db.ready_tasks
+puts "\n   Tasks ready after completing task1:"
+ready.each do |task|
+  puts "     [#{task.id}] P#{task.priority} #{task.type}: #{task.title}"
+end
+puts
+
+# =============================================================================
+# 10. Child Tasks (for Epics)
+# =============================================================================
+
+puts "10. Creating Child Tasks..."
+
+child1 = db.create_child_task(epic.id, {
+  title: "Setup OAuth providers",
+  type: "task",
+  priority: 2
+})
+puts "   Created child: [#{child1.id}] #{child1.title}"
+
+child2 = db.create_child_task(epic.id, {
+  title: "Add 2FA support",
+  type: "feature",
+  priority: 3
+})
+puts "   Created child: [#{child2.id}] #{child2.title}"
+
+children = db.child_tasks(epic.id)
+puts "   Epic #{epic.id} has #{children.size} children\n\n"
+
+# =============================================================================
+# 11. Plans and Workflows
+# =============================================================================
+
+puts "11. Plans and Workflows..."
+
+# Create a Plan (workflow blueprint)
+plan = TrakFlow::Models::Task.new(
+  title: "Deploy to Production",
+  plan: true
+)
+plan = db.create_task(plan)
+puts "   Created plan: [#{plan.id}] #{plan.title}"
+
+# Add steps to the plan
+step1 = db.create_child_task(plan.id, { title: "Run tests" })
+step2 = db.create_child_task(plan.id, { title: "Build artifacts" })
+step3 = db.create_child_task(plan.id, { title: "Deploy to staging" })
+puts "   Added #{db.find_plan_tasks(plan.id).size} steps to plan"
+
+# List all plans
+plans = db.find_plans
+puts "   Total plans: #{plans.size}"
+
+# Create an ephemeral task (temporary, garbage collectible)
+ephemeral = TrakFlow::Models::Task.new(
+  title: "Quick note: Check session timeout setting",
+  ephemeral: true
+)
+ephemeral = db.create_task(ephemeral)
+puts "   Created ephemeral task: [#{ephemeral.id}] #{ephemeral.title}"
+
+ephemeral_tasks = db.find_ephemeral_workflows
+puts "   Total ephemeral tasks: #{ephemeral_tasks.size}"
+
+# Garbage collection would remove old ephemeral tasks
+# gc_count = db.garbage_collect_ephemeral(max_age_hours: 24)
+puts
+
+# =============================================================================
+# Summary
+# =============================================================================
+
+puts <<~SUMMARY
+  ============================================================
+  Demo Complete!
+  ============================================================
+
+  What we demonstrated:
+  - Initialized TrakFlow database
+  - Configured settings via TrakFlow.configure
+  - Created tasks of various types (epic, task, feature, bug)
+  - Set up blocking and related dependencies
+  - Added labels and state labels (dimension:value)
+  - Added comments to tasks
+  - Queried tasks with filters
+  - Detected ready work vs blocked tasks
+  - Managed task lifecycle (open -> in_progress -> closed)
+  - Created child tasks under an epic
+  - Created Plans (workflow blueprints) with steps
+  - Created ephemeral tasks (temporary, garbage collectible)
+
+  Database location: #{db_path}
+  Dirty (needs flush): #{db.dirty?}
+
+SUMMARY
+
+# Cleanup
+db.close
+FileUtils.rm_rf(demo_dir)
+puts "Demo directory cleaned up."

data/examples/cli_demo.sh

@@ -0,0 +1,314 @@
+#!/usr/bin/env bash
+#
+# TrakFlow CLI Demo
+#
+# This script demonstrates how to use the `tf` command-line interface.
+# Run from the examples directory: ./cli_demo.sh
+#
+# Options:
+#   -n, --no-pause  Run without pausing between sections (for testing)
+#
+
+set -e
+
+# Parse options
+NO_PAUSE=false
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -n|--no-pause)
+      NO_PAUSE=true
+      shift
+      ;;
+    *)
+      shift
+      ;;
+  esac
+done
+
+# Determine project root and set up environment
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
+export PATH="$PROJECT_DIR/bin:$PATH"
+export BUNDLE_GEMFILE="$PROJECT_DIR/Gemfile"
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+header() {
+  echo ""
+  echo -e "${BLUE}============================================================${NC}"
+  echo -e "${BLUE}$1${NC}"
+  echo -e "${BLUE}============================================================${NC}"
+  echo ""
+}
+
+run_cmd() {
+  echo -e "${YELLOW}\$ $1${NC}"
+  eval "$1"
+  echo ""
+}
+
+pause() {
+  if [ "$NO_PAUSE" = false ]; then
+    echo -e "${GREEN}Press Enter to continue...${NC}"
+    read -r
+  fi
+}
+
+# Create temp directory for demo
+DEMO_DIR=$(mktemp -d -t trak_flow_demo)
+cd "$DEMO_DIR"
+
+cleanup() {
+  echo ""
+  echo -e "${RED}Cleaning up demo directory...${NC}"
+  rm -rf "$DEMO_DIR"
+  echo "Done."
+}
+trap cleanup EXIT
+
+header "TrakFlow CLI Demo"
+echo "Demo directory: $DEMO_DIR"
+echo ""
+
+# =============================================================================
+header "1. Initialize TrakFlow"
+# =============================================================================
+
+run_cmd "tf init"
+run_cmd "tf info"
+
+pause
+
+# =============================================================================
+header "2. Create Tasks"
+# =============================================================================
+
+echo "Creating various task types..."
+echo ""
+
+run_cmd "tf create 'Build user authentication' -t epic -p 1"
+run_cmd "tf create 'Design database schema' -t task -p 1 -d 'Create tables for users and sessions'"
+run_cmd "tf create 'Implement login endpoint' -t feature -p 2"
+run_cmd "tf create 'Write integration tests' -t task -p 3"
+run_cmd "tf create 'Fix password validation bug' -t bug -p 0"
+
+pause
+
+# =============================================================================
+header "3. List and Show Tasks"
+# =============================================================================
+
+run_cmd "tf list"
+run_cmd "tf list --status open"
+run_cmd "tf list --priority 0"
+
+echo "Showing task details (using first task ID from list)..."
+TASK_ID=$(tf list -j 2>/dev/null | ruby -roj -e 'puts Oj.load(STDIN.read).first["id"]')
+run_cmd "tf show $TASK_ID"
+
+pause
+
+# =============================================================================
+header "4. Dependencies"
+# =============================================================================
+
+echo "Setting up blocking dependencies..."
+echo ""
+
+# Get task IDs
+SCHEMA_ID=$(tf list -j 2>/dev/null | ruby -roj -e 'tasks = Oj.load(STDIN.read); puts tasks.find{|t| t["title"].include?("schema")}["id"]')
+LOGIN_ID=$(tf list -j 2>/dev/null | ruby -roj -e 'tasks = Oj.load(STDIN.read); puts tasks.find{|t| t["title"].include?("login")}["id"]')
+TEST_ID=$(tf list -j 2>/dev/null | ruby -roj -e 'tasks = Oj.load(STDIN.read); puts tasks.find{|t| t["title"].include?("tests")}["id"]')
+
+run_cmd "tf dep add $SCHEMA_ID $LOGIN_ID -t blocks"
+run_cmd "tf dep add $LOGIN_ID $TEST_ID -t blocks"
+
+echo "Viewing dependency tree..."
+run_cmd "tf dep tree $TEST_ID"
+
+pause
+
+# =============================================================================
+header "5. Ready Work Detection"
+# =============================================================================
+
+echo "Finding tasks that are ready to work on (not blocked)..."
+echo ""
+
+run_cmd "tf ready"
+
+pause
+
+# =============================================================================
+header "6. Labels"
+# =============================================================================
+
+BUG_ID=$(tf list -j 2>/dev/null | ruby -roj -e 'tasks = Oj.load(STDIN.read); puts tasks.find{|t| t["type"] == "bug"}["id"]')
+
+run_cmd "tf label add $BUG_ID critical"
+run_cmd "tf label add $BUG_ID security"
+run_cmd "tf label list $BUG_ID"
+run_cmd "tf label list-all"
+
+pause
+
+# =============================================================================
+header "7. Task Lifecycle"
+# =============================================================================
+
+echo "Updating task status..."
+echo ""
+
+run_cmd "tf update $BUG_ID --status in_progress"
+run_cmd "tf show $BUG_ID"
+
+echo "Closing the task..."
+run_cmd "tf close $BUG_ID -r 'Fixed regex to allow special characters'"
+run_cmd "tf show $BUG_ID"
+
+echo "Reopening if needed..."
+run_cmd "tf reopen $BUG_ID -r 'Found another edge case'"
+run_cmd "tf show $BUG_ID"
+
+pause
+
+# =============================================================================
+header "8. Child Tasks (Epics)"
+# =============================================================================
+
+EPIC_ID=$(tf list -j 2>/dev/null | ruby -roj -e 'tasks = Oj.load(STDIN.read); puts tasks.find{|t| t["type"] == "epic"}["id"]')
+
+echo "Creating child tasks under the epic..."
+echo ""
+
+run_cmd "tf create 'Setup OAuth providers' --parent $EPIC_ID -p 2"
+run_cmd "tf create 'Add 2FA support' --parent $EPIC_ID -p 3"
+
+run_cmd "tf show $EPIC_ID"
+
+pause
+
+# =============================================================================
+header "9. Plans and Workflows"
+# =============================================================================
+
+echo "Creating a Plan (workflow blueprint)..."
+echo ""
+
+run_cmd "tf plan create 'Deploy to Production' -d 'Standard deployment workflow'"
+
+PLAN_ID=$(tf plan list -j 2>/dev/null | ruby -roj -e 'puts Oj.load(STDIN.read).first["id"]')
+
+echo "Adding steps to the Plan..."
+run_cmd "tf plan add $PLAN_ID 'Run test suite' -p 1"
+run_cmd "tf plan add $PLAN_ID 'Build artifacts' -p 2"
+run_cmd "tf plan add $PLAN_ID 'Deploy to staging' -p 2"
+run_cmd "tf plan add $PLAN_ID 'Run smoke tests' -p 2"
+run_cmd "tf plan add $PLAN_ID 'Deploy to production' -p 1"
+
+run_cmd "tf plan show $PLAN_ID"
+run_cmd "tf plan list"
+
+pause
+
+# =============================================================================
+header "10. Starting Workflows from Plans"
+# =============================================================================
+
+echo "Starting a persistent Workflow from the Plan..."
+run_cmd "tf plan start $PLAN_ID"
+
+run_cmd "tf workflow list"
+
+WORKFLOW_ID=$(tf workflow list -j 2>/dev/null | ruby -roj -e 'puts Oj.load(STDIN.read).first["id"]')
+run_cmd "tf workflow show $WORKFLOW_ID"
+
+pause
+
+# =============================================================================
+header "11. Ephemeral Workflows"
+# =============================================================================
+
+echo "Creating an ephemeral (one-shot) Workflow..."
+run_cmd "tf plan execute $PLAN_ID"
+
+run_cmd "tf workflow list"
+run_cmd "tf workflow list -e"
+
+EPHEMERAL_ID=$(tf workflow list -e -j 2>/dev/null | ruby -roj -e 'puts Oj.load(STDIN.read).first["id"]')
+
+echo "Discarding the ephemeral Workflow..."
+run_cmd "tf workflow discard $EPHEMERAL_ID"
+
+run_cmd "tf workflow list"
+
+pause
+
+# =============================================================================
+header "12. Admin Commands"
+# =============================================================================
+
+echo "Analyzing the database..."
+run_cmd "tf admin compact --analyze"
+
+echo "Analyzing the dependency graph..."
+run_cmd "tf admin analyze"
+
+pause
+
+# =============================================================================
+header "13. JSON Output"
+# =============================================================================
+
+echo "All commands support -j for machine-readable output..."
+echo ""
+
+run_cmd "tf list -j | head -20"
+
+pause
+
+# =============================================================================
+header "14. Syncing with JSONL"
+# =============================================================================
+
+echo "TrakFlow stores data in both SQLite and JSONL formats."
+echo "The JSONL file is Git-friendly for version control."
+echo ""
+
+run_cmd "ls -la .trak_flow/"
+run_cmd "head -5 .trak_flow/issues.jsonl"
+
+pause
+
+# =============================================================================
+header "Demo Complete!"
+# =============================================================================
+
+cat << 'EOF'
+What we demonstrated:
+  - tf init          Initialize TrakFlow
+  - tf create        Create tasks (bug, feature, task, epic, chore)
+  - tf list          List tasks with filters
+  - tf show          Show task details
+  - tf update        Update task attributes
+  - tf close         Close a task
+  - tf reopen        Reopen a closed task
+  - tf ready         Find tasks ready to work on
+  - tf dep           Manage dependencies
+  - tf label         Manage labels
+  - tf plan          Create and manage workflow blueprints
+  - tf workflow      Manage running workflows
+  - tf admin         Administrative commands
+
+For more help:
+  tf --help
+  tf <command> --help
+EOF
+
+echo ""
+echo "Demo directory will be cleaned up on exit."

data/examples/mcp/Gemfile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gem "ruby_llm"
+gem "ruby_llm-mcp"
+
+# TrakFlow dependencies (needed when spawning tf_mcp via STDIO)
+gem "trak_flow", path: "../.."