sxn 0.2.5 → 0.4.0

data/lib/sxn/config/templates_config.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "pathname"
+
+module Sxn
+  module Config
+    # Handles loading and saving session templates from .sxn/templates.yml
+    #
+    # Templates define collections of projects (worktree configurations)
+    # that can be applied when creating a session.
+    class TemplatesConfig
+      TEMPLATES_FILE = "templates.yml"
+
+      attr_reader :sxn_path, :templates_file_path
+
+      def initialize(sxn_path)
+        @sxn_path = Pathname.new(sxn_path)
+        @templates_file_path = @sxn_path / TEMPLATES_FILE
+      end
+
+      # Load templates configuration from file
+      # @return [Hash] Templates configuration
+      def load
+        return default_config unless templates_file_path.exist?
+
+        content = File.read(templates_file_path)
+        config = YAML.safe_load(content, permitted_classes: [], permitted_symbols: [], aliases: false) || {}
+        normalize_config(config)
+      rescue Psych::SyntaxError => e
+        raise ConfigurationError, "Invalid YAML in #{templates_file_path}: #{e.message}"
+      rescue StandardError => e
+        raise ConfigurationError, "Failed to load templates file #{templates_file_path}: #{e.message}"
+      end
+
+      # Save templates configuration to file
+      # @param config [Hash] Templates configuration
+      def save(config)
+        ensure_directory_exists!
+
+        # Ensure version is set
+        config["version"] ||= 1
+        config["templates"] ||= {}
+
+        File.write(templates_file_path, YAML.dump(stringify_keys(config)))
+      end
+
+      # Check if templates file exists
+      # @return [Boolean]
+      def exists?
+        templates_file_path.exist?
+      end
+
+      # Get a specific template by name
+      # @param name [String] Template name
+      # @return [Hash, nil] Template configuration or nil if not found
+      def get_template(name)
+        config = load
+        templates = config["templates"] || {}
+        template = templates[name]
+
+        return nil unless template
+
+        # Normalize project entries to hashes
+        normalize_template(name, template)
+      end
+
+      # List all template names
+      # @return [Array<String>] Template names
+      def list_template_names
+        config = load
+        (config["templates"] || {}).keys
+      end
+
+      # Add or update a template
+      # @param name [String] Template name
+      # @param template [Hash] Template configuration
+      def set_template(name, template)
+        config = load
+        config["templates"] ||= {}
+        config["templates"][name] = template
+        save(config)
+      end
+
+      # Remove a template
+      # @param name [String] Template name
+      # @return [Boolean] True if template was removed
+      def remove_template(name)
+        config = load
+        templates = config["templates"] || {}
+
+        return false unless templates.key?(name)
+
+        templates.delete(name)
+        save(config)
+        true
+      end
+
+      private
+
+      def default_config
+        {
+          "version" => 1,
+          "templates" => {}
+        }
+      end
+
+      def normalize_config(config)
+        config["version"] ||= 1
+        config["templates"] ||= {}
+        config
+      end
+
+      def normalize_template(name, template)
+        {
+          "name" => name,
+          "description" => template["description"],
+          "projects" => normalize_projects(template["projects"] || [])
+        }
+      end
+
+      def normalize_projects(projects)
+        projects.map do |project|
+          if project.is_a?(String)
+            { "name" => project }
+          elsif project.is_a?(Hash)
+            # Ensure name key exists
+            project["name"] ||= project[:name]
+            stringify_keys(project)
+          else
+            { "name" => project.to_s }
+          end
+        end
+      end
+
+      def stringify_keys(hash)
+        return hash unless hash.is_a?(Hash)
+
+        hash.transform_keys(&:to_s).transform_values do |value|
+          case value
+          when Hash then stringify_keys(value)
+          when Array then value.map { |v| v.is_a?(Hash) ? stringify_keys(v) : v }
+          else value
+          end
+        end
+      end
+
+      def ensure_directory_exists!
+        FileUtils.mkdir_p(sxn_path) unless sxn_path.exist?
+      end
+    end
+  end
+end

data/lib/sxn/config.rb

@@ -3,6 +3,7 @@
 require_relative "config/config_discovery"
 require_relative "config/config_cache"
 require_relative "config/config_validator"
+require_relative "config/templates_config"
 
 module Sxn
   module Config

data/lib/sxn/core/session_config.rb

@@ -15,7 +15,7 @@ module Sxn
         @config_path = File.join(session_path, FILENAME)
       end
 
-      def create(parent_sxn_path:, default_branch:, session_name:)
+      def create(parent_sxn_path:, default_branch:, session_name:, template_id: nil)
         config = {
           "version" => 1,
           "parent_sxn_path" => parent_sxn_path,
@@ -23,6 +23,7 @@ module Sxn
           "session_name" => session_name,
           "created_at" => Time.now.iso8601
         }
+        config["template_id"] = template_id if template_id
         File.write(@config_path, YAML.dump(config))
         config
       end
@@ -51,6 +52,10 @@ module Sxn
         read&.dig("session_name")
       end
 
+      def template_id
+        read&.dig("template_id")
+      end
+
       def project_root
         parent_path = parent_sxn_path
         return nil unless parent_path

data/lib/sxn/core/session_manager.rb

@@ -13,7 +13,7 @@ module Sxn
         @database = initialize_database
       end
 
-      def create_session(name, description: nil, linear_task: nil, default_branch: nil)
+      def create_session(name, description: nil, linear_task: nil, default_branch: nil, template_id: nil)
         validate_session_name!(name)
         ensure_sessions_folder_exists!
 
@@ -31,10 +31,14 @@ module Sxn
         session_config.create(
           parent_sxn_path: @config_manager.sxn_folder_path,
           default_branch: branch,
-          session_name: name
+          session_name: name,
+          template_id: template_id
         )
 
-        # Create session record
+        # Create session record with template_id in metadata
+        metadata = {}
+        metadata["template_id"] = template_id if template_id
+
         session_data = {
           id: session_id,
           name: name,
@@ -46,7 +50,8 @@ module Sxn
           linear_task: linear_task,
           default_branch: branch,
           projects: [],
-          worktrees: {}
+          worktrees: {},
+          metadata: metadata
         }
 
         @database.create_session(session_data)
@@ -244,6 +249,7 @@ module Sxn
           description: metadata["description"] || db_row[:description],
           linear_task: metadata["linear_task"] || db_row[:linear_task],
           default_branch: metadata["default_branch"] || db_row[:default_branch],
+          template_id: metadata["template_id"],
           # Support both metadata and database columns for backward compatibility
           projects: db_row[:projects] || metadata["projects"] || [],
           worktrees: db_row[:worktrees] || metadata["worktrees"] || {}

data/lib/sxn/core/template_manager.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require_relative "../config/templates_config"
+
+module Sxn
+  module Core
+    # Manages session templates - collections of projects that can be
+    # applied when creating a session to automatically create multiple worktrees.
+    class TemplateManager
+      attr_reader :config_manager, :templates_config
+
+      def initialize(config_manager)
+        @config_manager = config_manager
+        @templates_config = Config::TemplatesConfig.new(config_manager.sxn_folder_path)
+      end
+
+      # List all available templates
+      # @return [Array<Hash>] Array of template info hashes
+      def list_templates
+        config = templates_config.load
+        templates = config["templates"] || {}
+
+        templates.map do |name, template|
+          {
+            name: name,
+            description: template["description"],
+            project_count: (template["projects"] || []).size
+          }
+        end
+      end
+
+      # Get a specific template by name
+      # @param name [String] Template name
+      # @return [Hash] Template configuration
+      # @raise [SessionTemplateNotFoundError] If template not found
+      def get_template(name)
+        template = templates_config.get_template(name)
+
+        unless template
+          available = list_template_names
+          raise SessionTemplateNotFoundError.new(name, available: available)
+        end
+
+        template
+      end
+
+      # Get list of template names
+      # @return [Array<String>] Template names
+      def list_template_names
+        templates_config.list_template_names
+      end
+
+      # Validate a template before use
+      # @param name [String] Template name
+      # @raise [SessionTemplateValidationError] If template is invalid
+      # @raise [SessionTemplateNotFoundError] If template not found
+      def validate_template(name)
+        template = get_template(name)
+        projects = template["projects"] || []
+        errors = []
+
+        errors << "Template has no projects defined" if projects.empty?
+
+        # Validate each project exists in config
+        projects.each do |project_config|
+          project_name = project_config["name"]
+          project = config_manager.get_project(project_name)
+
+          errors << "Project '#{project_name}' not found in configuration" unless project
+        end
+
+        raise SessionTemplateValidationError.new(name, errors.join("; ")) if errors.any?
+
+        true
+      end
+
+      # Create a new template
+      # @param name [String] Template name
+      # @param description [String] Template description
+      # @param projects [Array<String>] Array of project names
+      # @return [Hash] Created template
+      def create_template(name, description: nil, projects: [])
+        validate_template_name!(name)
+
+        raise SessionTemplateValidationError.new(name, "Template already exists") if template_exists?(name)
+
+        # Validate all projects exist
+        projects.each do |project_name|
+          project = config_manager.get_project(project_name)
+          raise SessionTemplateValidationError.new(name, "Project '#{project_name}' not found") unless project
+        end
+
+        template = {
+          "description" => description,
+          "projects" => projects.map { |p| { "name" => p } }
+        }
+
+        templates_config.set_template(name, template)
+
+        get_template(name)
+      end
+
+      # Update an existing template
+      # @param name [String] Template name
+      # @param description [String, nil] New description
+      # @param projects [Array<String>, nil] New project list
+      # @return [Hash] Updated template
+      def update_template(name, description: nil, projects: nil)
+        template = get_template(name)
+
+        # Update description if provided
+        template["description"] = description if description
+
+        # Update projects if provided
+        if projects
+          # Validate all projects exist
+          projects.each do |project_name|
+            project = config_manager.get_project(project_name)
+            raise SessionTemplateValidationError.new(name, "Project '#{project_name}' not found") unless project
+          end
+
+          template["projects"] = projects.map { |p| { "name" => p } }
+        end
+
+        # Save back to config
+        config = templates_config.load
+        config["templates"] ||= {}
+        config["templates"][name] = {
+          "description" => template["description"],
+          "projects" => template["projects"]
+        }
+        templates_config.save(config)
+
+        get_template(name)
+      end
+
+      # Remove a template
+      # @param name [String] Template name
+      # @return [Boolean] True if removed
+      def remove_template(name)
+        # Verify template exists
+        get_template(name)
+
+        templates_config.remove_template(name)
+      end
+
+      # Check if a template exists
+      # @param name [String] Template name
+      # @return [Boolean]
+      def template_exists?(name)
+        templates_config.get_template(name) != nil
+      end
+
+      # Get project configurations for a template with branch resolution
+      # @param name [String] Template name
+      # @param default_branch [String] Default branch to use if not specified per-project
+      # @return [Array<Hash>] Array of project configs with resolved branches
+      def get_template_projects(name, default_branch:)
+        template = get_template(name)
+        projects = template["projects"] || []
+
+        projects.map do |project_config|
+          project_name = project_config["name"]
+          project = config_manager.get_project(project_name)
+
+          {
+            name: project_name,
+            path: project[:path],
+            branch: project_config["branch"] || default_branch,
+            rules: project_config["rules"]
+          }
+        end
+      end
+
+      private
+
+      def validate_template_name!(name)
+        return if name.match?(/\A[a-zA-Z0-9_-]+\z/)
+
+        raise SessionTemplateValidationError.new(
+          name,
+          "Template name must contain only letters, numbers, hyphens, and underscores"
+        )
+      end
+    end
+  end
+end

data/lib/sxn/core.rb

@@ -6,6 +6,7 @@ require_relative "core/session_manager"
 require_relative "core/project_manager"
 require_relative "core/worktree_manager"
 require_relative "core/rules_manager"
+require_relative "core/template_manager"
 
 module Sxn
   # Core business logic namespace

data/lib/sxn/errors.rb

@@ -68,11 +68,34 @@ module Sxn
   class ApplicationError < Error; end
   class RollbackError < Error; end
 
-  # Template processing errors
+  # Template processing errors (Liquid templates)
   class TemplateError < Error; end
   class TemplateNotFoundError < TemplateError; end
   class TemplateProcessingError < TemplateError; end
 
+  # Session template errors (worktree templates)
+  class SessionTemplateError < Error; end
+
+  class SessionTemplateNotFoundError < SessionTemplateError
+    def initialize(name, available: [])
+      message = "Session template '#{name}' not found"
+      message += ". Available templates: #{available.join(", ")}" if available.any?
+      super(message)
+    end
+  end
+
+  class SessionTemplateValidationError < SessionTemplateError
+    def initialize(name, message)
+      super("Invalid session template '#{name}': #{message}")
+    end
+  end
+
+  class SessionTemplateApplicationError < SessionTemplateError
+    def initialize(template_name, message)
+      super("Failed to apply template '#{template_name}': #{message}. Session has been rolled back.")
+    end
+  end
+
   # Database errors
   class DatabaseError < Error; end
   class DatabaseConnectionError < DatabaseError; end

data/lib/sxn/mcp/prompts/workflow_prompts.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Sxn
+  module MCP
+    module Prompts
+      # Guided new session creation workflow
+      class NewSession < ::MCP::Prompt
+        prompt_name "new-session"
+        description "Guided workflow for creating a new development session"
+
+        arguments [
+          ::MCP::Prompt::Argument.new(
+            name: "task_description",
+            description: "Brief description of what you're working on",
+            required: false
+          ),
+          ::MCP::Prompt::Argument.new(
+            name: "projects",
+            description: "Comma-separated list of projects to include",
+            required: false
+          )
+        ]
+
+        class << self
+          def template(args = {}, _server_context: nil)
+            # Handle both string and symbol keys
+            task_description = args["task_description"] || args[:task_description]
+            projects = args["projects"] || args[:projects]
+            project_list = projects ? projects.split(",").map(&:strip).join(", ") : "Not specified"
+
+            <<~PROMPT
+              # Create a New Development Session
+
+              Help me create a new sxn development session.
+
+              ## Task Information
+              - Description: #{task_description || "Not provided"}
+              - Requested projects: #{project_list}
+
+              ## Steps to Complete
+
+              1. **Generate session name** based on the task description
+              2. **Create the session** using sxn_sessions_create
+              3. **Add worktrees** for each requested project using sxn_worktrees_add
+              4. **Navigate to the session** using sxn_sessions_swap
+
+              ## Guidelines
+              - Session names should be descriptive but concise (e.g., "user-auth", "api-refactor")
+              - Use alphanumeric characters, hyphens, and underscores only
+              - Apply project rules automatically when creating worktrees
+            PROMPT
+          end
+        end
+      end
+
+      # Multi-repo setup workflow
+      class MultiRepoSetup < ::MCP::Prompt
+        prompt_name "multi-repo-setup"
+        description "Set up a multi-repository development environment"
+
+        arguments [
+          ::MCP::Prompt::Argument.new(
+            name: "feature_name",
+            description: "Name of the feature being developed across repos",
+            required: true
+          ),
+          ::MCP::Prompt::Argument.new(
+            name: "repos",
+            description: "Comma-separated list of repository names to include",
+            required: false
+          )
+        ]
+
+        class << self
+          def template(args = {}, _server_context: nil)
+            # Handle both string and symbol keys
+            feature_name = args["feature_name"] || args[:feature_name]
+            repos = args["repos"] || args[:repos]
+            repo_list = repos ? repos.split(",").map(&:strip) : []
+
+            <<~PROMPT
+              # Multi-Repository Development Setup
+
+              Set up a coordinated development environment for: **#{feature_name}**
+
+              ## Repositories to Include
+              #{repo_list.empty? ? "- (Will use sxn_projects_list to find available projects)" : repo_list.map { |r| "- #{r}" }.join("\n")}
+
+              ## Setup Process
+
+              1. **Check registered projects** with sxn_projects_list
+              2. **Create the session** with sxn_sessions_create
+                 - Name: #{feature_name.downcase.gsub(/\s+/, "-")}
+              3. **Add worktrees** for each repository with sxn_worktrees_add
+              4. **Apply rules** with sxn_rules_apply for each project
+              5. **Navigate** using sxn_sessions_swap
+
+              ## Best Practices
+              - Use the same branch name across all repos
+              - Apply rules to copy environment files
+            PROMPT
+          end
+        end
+      end
+    end
+  end
+end