sxn 0.2.5 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30ceb6fb94a023b31e9b9c4c4354806a5343b7cefa8f1b43047011f86e3048cf
-  data.tar.gz: 071b888de74d9e284376acf2ed425a5a33ddf329ac01112bc3fbc65acc8dd363
+  metadata.gz: 52c6ed94883c7981bdbc6bc0a2faa9d800dbe81fd4af0ee7af41dda777e95421
+  data.tar.gz: 1724ced66383451b1d914285b996a8d2c8bc82643fb08a0eb674a8c0c23a6e06
 SHA512:
-  metadata.gz: 93cb3f85f80ccc13ffcc62662fa86bd0e8b7531105ab08dc49f0213744a858bbaf7fff8823c2d5358617704eeb5aae6f2264ba02f20e14c71003fd8e912136d4
-  data.tar.gz: fc1e076616d354218525d2d8ee6a6454a04dfd5d1db969f7032792c91ec1679605a4d0351573a57cd3b5af64c8d06fdecad1068b51dfd66bc2bea5c92bc52dfc
+  metadata.gz: ec072a5436b75710595263f5667828a83d0c5c42aa44f8cde622550762b30fd1ce3b244636bbf57df70b89eeda2c765abbfd04b6b80ff3c4998358e8bad4afe2
+  data.tar.gz: d1d7fa0c3acc68746767376f8f201004c74e8930ce8069b69aa4ad080b7338d4f21da7743cfd704e20746e942ddeca497fc7baa7f81c3a4d7c638e3b6a8437eb

data/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2025-12-16
+
+### Added
+- Session templates support for creating sessions from predefined configurations
+  - `sxn templates list` to view available templates
+  - `sxn templates show <name>` to view template details
+  - `--template` option for `sxn sessions add` to create sessions from templates
+- TemplateManager for template operations and validation
+- TemplatesConfig for loading templates from `templates.yml`
+- Session template error classes for better error handling
+
+### Fixed
+- Project rules now correctly apply when creating sessions from templates
+
 ## [0.2.5] - 2025-11-30
 
 ### Added
@@ -101,6 +115,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Initial placeholder release
 - Basic gem structure
 
+[0.3.0]: https://github.com/idl3/sxn/compare/v0.2.5...v0.3.0
+[0.2.5]: https://github.com/idl3/sxn/compare/v0.2.4...v0.2.5
 [0.2.4]: https://github.com/idl3/sxn/compare/v0.2.3...v0.2.4
 [0.2.3]: https://github.com/idl3/sxn/compare/v0.2.1...v0.2.3
 [0.2.1]: https://github.com/idl3/sxn/compare/v0.2.0...v0.2.1

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    sxn (0.2.5)
+    sxn (0.3.0)
       async (~> 2.0)
       bcrypt (~> 3.1)
       dry-configurable (~> 1.0)

data/lib/sxn/CLI.rb

@@ -42,6 +42,7 @@ module Sxn
     option :description, type: :string, aliases: "-d", desc: "Session description"
     option :linear_task, type: :string, aliases: "-l", desc: "Linear task ID"
     option :branch, type: :string, aliases: "-b", desc: "Default branch for worktrees"
+    option :template, type: :string, aliases: "-t", desc: "Template to use for worktree creation"
     def add(session_name)
       cmd = Commands::Sessions.new
       cmd.options = options
@@ -217,6 +218,13 @@ module Sxn
       handle_error(e)
     end
 
+    desc "templates SUBCOMMAND", "Manage session templates"
+    def templates(subcommand = nil, *args)
+      Commands::Templates.start([subcommand, *args].compact)
+    rescue Sxn::Error => e
+      handle_error(e)
+    end
+
     desc "status", "Show overall sxn status"
     def status
       show_status

data/lib/sxn/commands/sessions.rb

@@ -19,12 +19,14 @@ module Sxn
         @session_manager = Sxn::Core::SessionManager.new(@config_manager)
         @project_manager = Sxn::Core::ProjectManager.new(@config_manager)
         @worktree_manager = Sxn::Core::WorktreeManager.new(@config_manager, @session_manager)
+        @template_manager = Sxn::Core::TemplateManager.new(@config_manager)
       end
 
       desc "add NAME", "Create a new session"
       option :description, type: :string, aliases: "-d", desc: "Session description"
       option :linear_task, type: :string, aliases: "-l", desc: "Linear task ID"
       option :branch, type: :string, aliases: "-b", desc: "Default branch for worktrees"
+      option :template, type: :string, aliases: "-t", desc: "Template to use for worktree creation"
       option :activate, type: :boolean, default: true, desc: "Activate session after creation"
       option :skip_worktree, type: :boolean, default: false, desc: "Skip worktree creation wizard"
 
@@ -37,9 +39,29 @@ module Sxn
           name = @prompt.session_name(existing_sessions: existing_sessions)
         end
 
+        template_id = options[:template]
+
+        # Validate template if specified
+        if template_id
+          begin
+            @template_manager.validate_template(template_id)
+          rescue Sxn::SessionTemplateNotFoundError, Sxn::SessionTemplateValidationError => e
+            @ui.error(e.message)
+            exit(1)
+          end
+        end
+
         # Get default branch - use provided option, or prompt interactively
+        # Branch is required when using a template
         default_branch = options[:branch]
-        default_branch ||= @prompt.default_branch(session_name: name)
+        if default_branch.nil?
+          if template_id
+            @ui.error("Branch is required when using a template. Use -b/--branch to specify.")
+            exit(1)
+          else
+            default_branch = @prompt.default_branch(session_name: name)
+          end
+        end
 
         begin
           @ui.progress_start("Creating session '#{name}'")
@@ -48,7 +70,8 @@ module Sxn
             name,
             description: options[:description],
             linear_task: options[:linear_task],
-            default_branch: default_branch
+            default_branch: default_branch,
+            template_id: template_id
           )
 
           @ui.progress_done
@@ -60,8 +83,13 @@ module Sxn
 
           display_session_info(session)
 
-          # Offer to add a worktree unless skipped
-          offer_worktree_wizard(name) unless options[:skip_worktree]
+          # Apply template if specified (with atomic rollback on failure)
+          if template_id
+            apply_template_to_session(name, template_id, default_branch)
+          elsif !options[:skip_worktree]
+            # Offer to add a worktree unless skipped or template was used
+            offer_worktree_wizard(name)
+          end
         rescue Sxn::Error => e
           @ui.progress_failed
           @ui.error(e.message)
@@ -275,6 +303,88 @@ module Sxn
 
       private
 
+      def apply_template_to_session(session_name, template_id, default_branch)
+        template = @template_manager.get_template(template_id)
+        projects = template["projects"] || []
+        created_worktrees = []
+
+        @ui.newline
+        @ui.section("Applying Template '#{template_id}'")
+        @ui.info("Creating #{projects.size} worktree(s)...")
+
+        begin
+          projects.each_with_index do |project_config, index|
+            project_name = project_config["name"]
+            # Use project-specific branch override, or fall back to session default
+            branch = project_config["branch"] || default_branch
+
+            @ui.progress_start("Creating worktree #{index + 1}/#{projects.size}: #{project_name}")
+
+            worktree = @worktree_manager.add_worktree(
+              project_name,
+              branch,
+              session_name: session_name
+            )
+            created_worktrees << worktree
+
+            @ui.progress_done
+
+            # Apply project's default rules first
+            apply_project_rules(project_name, session_name)
+
+            # Apply template-specific rule overrides if defined (in addition to project defaults)
+            apply_template_rules(session_name, project_name, worktree[:path], project_config["rules"]) if project_config["rules"]
+          end
+
+          @ui.newline
+          @ui.success("Template applied: #{created_worktrees.size} worktree(s) created")
+
+          # Display created worktrees
+          @ui.newline
+          @ui.subsection("Created Worktrees")
+          created_worktrees.each do |wt|
+            @ui.list_item("#{wt[:project]} (#{wt[:branch]}) → #{wt[:path]}")
+          end
+        rescue StandardError => e
+          # ATOMIC ROLLBACK: Remove all created worktrees and the session
+          @ui.progress_failed
+          @ui.newline
+          @ui.warning("Template application failed, rolling back...")
+
+          rollback_template_application(session_name, created_worktrees)
+
+          raise Sxn::SessionTemplateApplicationError.new(template_id, e.message)
+        end
+      end
+
+      def rollback_template_application(session_name, created_worktrees)
+        # Remove created worktrees
+        created_worktrees.each do |wt|
+          @worktree_manager.remove_worktree(wt[:project], session_name: session_name)
+        rescue StandardError
+          # Best effort cleanup, continue with rollback
+          nil
+        end
+
+        # Remove the session
+        @session_manager.remove_session(session_name, force: true)
+        @ui.info("Session '#{session_name}' has been rolled back")
+      rescue StandardError => e
+        @ui.warning("Rollback encountered errors: #{e.message}")
+      end
+
+      def apply_template_rules(_session_name, project_name, worktree_path, rules)
+        return unless rules.is_a?(Hash)
+
+        rules_manager = Sxn::Core::RulesManager.new(@config_manager, worktree_path)
+
+        rules_manager.apply_copy_files_rules(rules["copy_files"]) if rules["copy_files"]
+
+        rules_manager.apply_setup_commands(rules["setup_commands"]) if rules["setup_commands"]
+      rescue StandardError => e
+        @ui.warning("Failed to apply rules for #{project_name}: #{e.message}")
+      end
+
       def ensure_initialized!
         return if @config_manager.initialized?
 

data/lib/sxn/commands/templates.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module Sxn
+  module Commands
+    # Manage session templates
+    class Templates < Thor
+      include Thor::Actions
+
+      def initialize(args = ARGV, local_options = {}, config = {})
+        super
+        @ui = Sxn::UI::Output.new
+        @prompt = Sxn::UI::Prompt.new
+        @table = Sxn::UI::Table.new
+        @config_manager = Sxn::Core::ConfigManager.new
+        @template_manager = Sxn::Core::TemplateManager.new(@config_manager)
+        @project_manager = Sxn::Core::ProjectManager.new(@config_manager)
+      end
+
+      desc "list", "List available session templates"
+
+      def list
+        ensure_initialized!
+
+        templates = @template_manager.list_templates
+
+        @ui.section("Session Templates")
+
+        if templates.empty?
+          @ui.empty_state("No templates defined")
+          @ui.newline
+          @ui.recovery_suggestion("Create a template with 'sxn templates create'")
+          @ui.recovery_suggestion("Or manually edit .sxn/templates.yml")
+        else
+          display_templates_table(templates)
+          @ui.newline
+          @ui.info("Total: #{templates.size} template(s)")
+        end
+      rescue Sxn::Error => e
+        @ui.error(e.message)
+        exit(e.exit_code)
+      end
+
+      desc "show NAME", "Show details of a session template"
+
+      def show(name)
+        ensure_initialized!
+
+        template = @template_manager.get_template(name)
+
+        @ui.section("Template: #{name}")
+        @ui.key_value("Description", template["description"] || "(none)")
+        @ui.key_value("Projects", (template["projects"] || []).size.to_s)
+
+        @ui.newline
+        @ui.subsection("Projects")
+
+        projects = template["projects"] || []
+        if projects.empty?
+          @ui.empty_state("No projects in this template")
+        else
+          projects.each do |project_config|
+            project_name = project_config["name"]
+            project = begin
+              @project_manager.get_project(project_name)
+            rescue Sxn::ProjectNotFoundError
+              nil
+            end
+            status = project ? "✓" : "✗ (not found)"
+
+            details = []
+            details << "branch: #{project_config["branch"]}" if project_config["branch"]
+            details << "has custom rules" if project_config["rules"]
+
+            if details.any?
+              @ui.list_item("#{project_name} #{status} (#{details.join(", ")})")
+            else
+              @ui.list_item("#{project_name} #{status}")
+            end
+          end
+        end
+
+        @ui.newline
+        @ui.subsection("Usage")
+        @ui.command_example(
+          "sxn add my-session -t #{name} -b my-branch",
+          "Create session with this template"
+        )
+      rescue Sxn::SessionTemplateNotFoundError => e
+        @ui.error(e.message)
+        exit(1)
+      rescue Sxn::Error => e
+        @ui.error(e.message)
+        exit(e.exit_code)
+      end
+
+      desc "create", "Create a new session template"
+      option :name, type: :string, aliases: "-n", desc: "Template name"
+      option :description, type: :string, aliases: "-d", desc: "Template description"
+
+      def create
+        ensure_initialized!
+
+        # Get template name
+        name = options[:name]
+        if name.nil?
+          name = @prompt.ask("Template name:")
+          if name.nil? || name.strip.empty?
+            @ui.error("Template name is required")
+            exit(1)
+          end
+        end
+
+        # Check if template already exists
+        if @template_manager.template_exists?(name)
+          @ui.error("Template '#{name}' already exists")
+          @ui.recovery_suggestion("Use a different name or remove existing template with 'sxn templates remove #{name}'")
+          exit(1)
+        end
+
+        # Get description
+        description = options[:description]
+        description ||= @prompt.ask("Description (optional):")
+
+        # Select projects
+        projects = @project_manager.list_projects
+        if projects.empty?
+          @ui.error("No projects configured")
+          @ui.recovery_suggestion("Add projects with 'sxn projects add <name> <path>' first")
+          exit(1)
+        end
+
+        @ui.newline
+        @ui.info("Select projects to include in the template:")
+        @ui.info("(Use space to select, enter to confirm)")
+        @ui.newline
+
+        project_choices = projects.map do |p|
+          { name: "#{p[:name]} (#{p[:type] || "unknown"})", value: p[:name] }
+        end
+
+        selected_projects = @prompt.multi_select("Projects:", project_choices)
+
+        if selected_projects.empty?
+          @ui.error("At least one project must be selected")
+          exit(1)
+        end
+
+        # Create the template
+        @ui.progress_start("Creating template '#{name}'")
+
+        @template_manager.create_template(
+          name,
+          description: description,
+          projects: selected_projects
+        )
+
+        @ui.progress_done
+        @ui.success("Template '#{name}' created with #{selected_projects.size} project(s)")
+
+        @ui.newline
+        @ui.subsection("Usage")
+        @ui.command_example(
+          "sxn add my-session -t #{name} -b my-branch",
+          "Create session with this template"
+        )
+      rescue Sxn::SessionTemplateValidationError => e
+        @ui.progress_failed
+        @ui.error(e.message)
+        exit(1)
+      rescue Sxn::Error => e
+        @ui.progress_failed
+        @ui.error(e.message)
+        exit(e.exit_code)
+      end
+
+      desc "remove NAME", "Remove a session template"
+      option :force, type: :boolean, aliases: "-f", desc: "Skip confirmation"
+
+      def remove(name = nil)
+        ensure_initialized!
+
+        # Interactive selection if name not provided
+        if name.nil?
+          templates = @template_manager.list_templates
+          if templates.empty?
+            @ui.empty_state("No templates to remove")
+            return
+          end
+
+          choices = templates.map { |t| { name: "#{t[:name]} - #{t[:description] || "(no description)"}", value: t[:name] } }
+          name = @prompt.select("Select template to remove:", choices)
+        end
+
+        # Verify template exists
+        @template_manager.get_template(name)
+
+        # Confirm deletion unless force flag is used
+        return if !options[:force] && !@prompt.confirm_deletion(name, "template")
+
+        @ui.progress_start("Removing template '#{name}'")
+        @template_manager.remove_template(name)
+        @ui.progress_done
+        @ui.success("Template '#{name}' removed")
+      rescue Sxn::SessionTemplateNotFoundError => e
+        @ui.error(e.message)
+        exit(1)
+      rescue Sxn::Error => e
+        @ui.progress_failed
+        @ui.error(e.message)
+        exit(e.exit_code)
+      end
+
+      private
+
+      def ensure_initialized!
+        return if @config_manager.initialized?
+
+        @ui.error("Project not initialized")
+        @ui.recovery_suggestion("Run 'sxn init' to initialize sxn in this project")
+        exit(1)
+      end
+
+      def display_templates_table(templates)
+        @table.templates(templates)
+      end
+    end
+  end
+end

data/lib/sxn/commands.rb

@@ -5,6 +5,7 @@ require_relative "commands/sessions"
 require_relative "commands/projects"
 require_relative "commands/worktrees"
 require_relative "commands/rules"
+require_relative "commands/templates"
 
 module Sxn
   # Commands namespace for all CLI command implementations

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/ui/table.rb

@@ -89,6 +89,21 @@ module Sxn
         render_table(headers, rows)
       end
 
+      def templates(templates)
+        return empty_table("No templates defined") if templates.empty?
+
+        headers = %w[Name Description Projects]
+        rows = templates.map do |template|
+          [
+            template[:name],
+            template[:description] || "-",
+            template[:project_count].to_s
+          ]
+        end
+
+        render_table(headers, rows)
+      end
+
       # Add a header to the table output
       def header(title)
         puts "\n#{@pastel.bold.underline(title)}"
@@ -99,7 +114,9 @@ module Sxn
 
       def render_table(headers, rows)
         table = TTY::Table.new(header: headers, rows: rows)
-        puts table.render(:unicode, padding: [0, 1])
+        # Use basic renderer to avoid terminal width detection issues
+        renderer = $stdout.tty? ? :unicode : :basic
+        puts table.render(renderer, padding: [0, 1])
       end
 
       def empty_table(message)

data/lib/sxn/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Sxn
-  VERSION = "0.2.5"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sxn
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.3.0
 platform: ruby
 authors:
 - Ernest Sim
@@ -509,17 +509,20 @@ files:
 - lib/sxn/commands/projects.rb
 - lib/sxn/commands/rules.rb
 - lib/sxn/commands/sessions.rb
+- lib/sxn/commands/templates.rb
 - lib/sxn/commands/worktrees.rb
 - lib/sxn/config.rb
 - lib/sxn/config/config_cache.rb
 - lib/sxn/config/config_discovery.rb
 - lib/sxn/config/config_validator.rb
+- lib/sxn/config/templates_config.rb
 - lib/sxn/core.rb
 - lib/sxn/core/config_manager.rb
 - lib/sxn/core/project_manager.rb
 - lib/sxn/core/rules_manager.rb
 - lib/sxn/core/session_config.rb
 - lib/sxn/core/session_manager.rb
+- lib/sxn/core/template_manager.rb
 - lib/sxn/core/worktree_manager.rb
 - lib/sxn/database.rb
 - lib/sxn/database/errors.rb
@@ -611,7 +614,6 @@ files:
 - sig/sxn/ui/prompt.rbs
 - sig/sxn/ui/table.rbs
 - sig/sxn/version.rbs
-- sxn.gemspec
 homepage: https://github.com/idl3/sxn
 licenses:
 - MIT

data/sxn.gemspec

@@ -1,85 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "lib/sxn/version"
-
-Gem::Specification.new do |spec|
-  spec.name          = "sxn"
-  spec.version       = Sxn::VERSION
-  spec.authors       = ["Ernest Sim"]
-  spec.email         = ["ernest.codes@gmail.com"]
-
-  spec.summary       = "Session management for multi-repository development"
-  spec.description   = "Sxn simplifies git worktree management with intelligent project rules and secure automation"
-  spec.homepage      = "https://github.com/idl3/sxn"
-  spec.license       = "MIT"
-  spec.required_ruby_version = ">= 3.2.0"
-
-  spec.metadata["allowed_push_host"] = "https://rubygems.org"
-  spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = spec.homepage
-  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
-  spec.metadata["rubygems_mfa_required"] = "true"
-
-  # Specify which files should be added to the gem when it is released.
-  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
-  spec.files = Dir.chdir(File.expand_path(__dir__)) do
-    `git ls-files -z`.split("\x0").reject do |f|
-      (f == __FILE__) ||
-        f.match(%r{\A(?:(?:test|spec|features)/|\.(?:git|travis|circleci)|appveyor)}) ||
-        f.match(/\.db-(?:shm|wal)\z/) || # Exclude SQLite temp files
-        f.match(/\.gem\z/) # Exclude gem files
-    end
-  end
-
-  spec.bindir        = "bin"
-  spec.executables   = spec.files.grep(%r{\Abin/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
-
-  # Core CLI dependencies
-  spec.add_dependency "pastel", "~> 0.8"                  # Terminal colors
-  spec.add_dependency "thor", "~> 1.3"                    # CLI framework
-  spec.add_dependency "tty-progressbar", "~> 0.18"        # Progress bars
-  spec.add_dependency "tty-prompt", "~> 0.23"             # Interactive prompts
-  spec.add_dependency "tty-table", "~> 0.12"              # Table formatting
-
-  # Configuration and data management
-  spec.add_dependency "dry-configurable", "~> 1.0"       # Configuration management
-  spec.add_dependency "sqlite3", "~> 1.6"                # Session database
-  spec.add_dependency "zeitwerk", "~> 2.6"               # Code loading
-
-  # Template engine (secure, sandboxed)
-  spec.add_dependency "liquid", "~> 5.4" # Safe template processing
-
-  # MCP server dependencies
-  spec.add_dependency "async", "~> 2.0"                  # Async operations
-  spec.add_dependency "json-schema", "~> 4.0"            # Schema validation
-
-  # Security and encryption
-  spec.add_dependency "bcrypt", "~> 3.1"                 # Password hashing
-  spec.add_dependency "openssl", ">= 3.0"                # Encryption support
-  spec.add_dependency "ostruct"                          # OpenStruct for Ruby 3.5+ compatibility
-
-  # File system operations
-  spec.add_dependency "listen", "~> 3.8"                 # File watching for config cache
-  spec.add_dependency "parallel", "~> 1.23"              # Parallel execution
-
-  # Development dependencies
-  spec.add_development_dependency "aruba", "~> 2.1" # CLI testing
-  spec.add_development_dependency "benchmark" # Benchmark for Ruby 3.5+ compatibility
-  spec.add_development_dependency "benchmark-ips", "~> 2.12" # Performance benchmarking
-  spec.add_development_dependency "bundler", "~> 2.4"
-  spec.add_development_dependency "climate_control", "~> 1.2" # Environment variable testing
-  spec.add_development_dependency "faker", "~> 3.2" # Test data generation
-  spec.add_development_dependency "memory_profiler", "~> 1.0" # Memory profiling
-  spec.add_development_dependency "rake", "~> 13.0"
-  spec.add_development_dependency "rspec", "~> 3.12"
-  spec.add_development_dependency "rubocop", "~> 1.50" # Code linting
-  spec.add_development_dependency "rubocop-performance", "~> 1.16"
-  spec.add_development_dependency "rubocop-rspec", "~> 2.19"
-  spec.add_development_dependency "simplecov", "~> 0.22" # Code coverage
-  spec.add_development_dependency "vcr", "~> 6.2" # HTTP interaction recording
-  spec.add_development_dependency "webmock", "~> 3.19" # HTTP mocking for MCP tests
-
-  # For more information and examples about making a new gem, check out our
-  # guide at: https://bundler.io/guides/creating_gem.html
-end