kairos-chain 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 89223ad42654fe812b9219cfeb4d136101e3cf88054cd0dc8f99999c993af43a
+  data.tar.gz: c75b155784af0ce1782c67bb5f925b83428ffbab463150567a0bdb04798ced66
+SHA512:
+  metadata.gz: 007d915cbb44e3ed2834a1c176dbf28ea9631b7ef2ea88c934e20926f3dace4058f4ea393327dbf5a0923070b5ac35526a88dcae9d25f22f761eef3d38ba40d3
+  data.tar.gz: baf5e843902f5e7d3b09dc62087c1dbadd1cda17055400d5a6acc66de9b9df3431507aa551eb61984596b2d84c15c7d23af54cfd4d4ece6387ee42810862aac2

data/bin/kairos-chain

@@ -0,0 +1,255 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# KairosChain - Memory-driven agent framework
+#
+# Usage:
+#   kairos-chain                        # stdio mode (default, for Cursor local)
+#   kairos-chain --http                 # Streamable HTTP mode (remote access)
+#   kairos-chain --http --port 9090
+#   kairos-chain --init-admin           # Generate initial admin token
+#   kairos-chain init [DIR]             # Initialize data directory with templates
+#   kairos-chain init --data-dir /path  # Initialize at specific path
+#   kairos-chain upgrade                # Preview template migrations after gem update
+#   kairos-chain upgrade --apply        # Apply template migrations
+#
+# Data directory resolution (priority order):
+#   1. --data-dir CLI option
+#   2. KAIROS_DATA_DIR environment variable
+#   3. .kairos/ in the current working directory
+#
+# Streamable HTTP mode requires: gem install puma rack
+
+require 'optparse'
+
+# Check for subcommands first (before OptionParser)
+case ARGV[0]
+when 'init'
+  ARGV.shift  # Remove 'init' from ARGV
+
+  init_options = {}
+  OptionParser.new do |opts|
+    opts.banner = "Usage: kairos-chain init [options] [DIR]"
+
+    opts.on('--data-dir DIR', 'Data directory path (default: .kairos/)') do |dir|
+      init_options[:data_dir] = dir
+    end
+
+    opts.on('-h', '--help', 'Show help') do
+      puts opts
+      exit
+    end
+  end.parse!
+
+  # Remaining argument is the directory
+  init_dir = init_options[:data_dir] || ARGV.shift
+
+  # Setup load path and require entry point
+  $LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+  require 'kairos_mcp'
+
+  # Set data_dir if specified, otherwise use default
+  if init_dir
+    KairosMcp.data_dir = File.expand_path(init_dir)
+  end
+
+  require 'kairos_mcp/initializer'
+  KairosMcp::Initializer.run
+  exit
+
+when 'upgrade'
+  ARGV.shift  # Remove 'upgrade' from ARGV
+
+  upgrade_options = {}
+  OptionParser.new do |opts|
+    opts.banner = "Usage: kairos-chain upgrade [options]"
+
+    opts.on('--data-dir DIR', 'Data directory path (default: .kairos/)') do |dir|
+      upgrade_options[:data_dir] = dir
+    end
+
+    opts.on('--apply', 'Apply the upgrade (default: preview only)') do
+      upgrade_options[:apply] = true
+    end
+
+    opts.on('-h', '--help', 'Show help') do
+      puts opts
+      exit
+    end
+  end.parse!
+
+  # Setup load path and require entry point
+  $LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+  require 'kairos_mcp'
+
+  # Set data_dir if specified
+  if upgrade_options[:data_dir]
+    KairosMcp.data_dir = File.expand_path(upgrade_options[:data_dir])
+  end
+
+  require 'kairos_mcp/upgrade_analyzer'
+  require 'kairos_mcp/config_merger'
+  require 'kairos_mcp/tools/system_upgrade'
+
+  # Create a minimal tool instance for CLI use
+  tool = KairosMcp::Tools::SystemUpgrade.new
+  command = upgrade_options[:apply] ? 'apply' : 'preview'
+  result = tool.call({ 'command' => command, 'approved' => upgrade_options[:apply] || false })
+
+  # Extract text from MCP response format
+  result.each do |content|
+    puts content[:text] if content[:type] == 'text'
+  end
+  exit
+end
+
+# Parse CLI options
+options = {}
+
+OptionParser.new do |opts|
+  opts.banner = "Usage: kairos-chain [options]"
+
+  opts.on('--data-dir DIR', 'Data directory path (default: .kairos/ or KAIROS_DATA_DIR)') do |dir|
+    options[:data_dir] = dir
+  end
+
+  opts.on('--http', 'Start in Streamable HTTP mode (default: stdio)') do
+    options[:http] = true
+  end
+
+  opts.on('--port PORT', Integer, 'HTTP port (default: 8080)') do |port|
+    options[:port] = port
+  end
+
+  opts.on('--host HOST', 'HTTP bind host (default: 0.0.0.0)') do |host|
+    options[:host] = host
+  end
+
+  opts.on('--init-admin', 'Generate initial admin token and exit') do
+    options[:init_admin] = true
+  end
+
+  opts.on('--token-store PATH', 'Path to token store file') do |path|
+    options[:token_store] = path
+  end
+
+  opts.on('-v', '--version', 'Show version') do
+    options[:version] = true
+  end
+
+  opts.on('-h', '--help', 'Show help') do
+    puts opts
+    puts ""
+    puts "Subcommands:"
+    puts "  init [DIR]          Initialize data directory with default templates"
+    puts "  upgrade [--apply]   Check/apply template migrations after gem update"
+    exit
+  end
+end.parse!
+
+# Setup bundler if Gemfile exists (enables optional gems)
+gemfile_path = File.expand_path('../Gemfile', __dir__)
+if File.exist?(gemfile_path)
+  ENV['BUNDLE_GEMFILE'] ||= gemfile_path
+  # Use local vendor/bundle if it exists
+  vendor_path = File.expand_path('../vendor/bundle', __dir__)
+  ENV['BUNDLE_PATH'] ||= vendor_path if File.directory?(vendor_path)
+  begin
+    require 'bundler/setup'
+  rescue Bundler::GemNotFound, LoadError
+    # Fall back to running without bundler if gems not installed
+    warn "[KairosChain] Bundler gems not found, running without optional dependencies"
+  end
+end
+
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+
+# Load entry point
+require 'kairos_mcp'
+
+# Set data_dir if specified via CLI
+if options[:data_dir]
+  KairosMcp.data_dir = File.expand_path(options[:data_dir])
+end
+
+# Handle --version
+if options[:version]
+  puts "KairosChain MCP Server v#{KairosMcp::VERSION}"
+  puts "Data directory: #{KairosMcp.data_dir}"
+  exit
+end
+
+# Handle --init-admin
+if options[:init_admin]
+  require 'kairos_mcp/auth/token_store'
+
+  store = KairosMcp::Auth::TokenStore.new(options[:token_store])
+
+  if !store.empty?
+    $stderr.puts "[WARNING] Active tokens already exist."
+    $stderr.puts "Use the token_manage MCP tool to create additional tokens."
+    $stderr.puts ""
+    $stderr.puts "Existing tokens:"
+    store.list.each do |t|
+      $stderr.puts "  - #{t[:user]} (#{t[:role]}, expires: #{t[:expires_at] || 'never'})"
+    end
+    $stderr.puts ""
+    $stderr.puts "Proceed anyway? (y/N)"
+    answer = $stdin.gets&.strip
+    exit unless answer&.downcase == 'y'
+  end
+
+  result = store.create(user: 'admin', role: 'owner', issued_by: 'system')
+
+  puts ""
+  puts "=" * 60
+  puts "  KairosChain Admin Token Generated"
+  puts "=" * 60
+  puts ""
+  puts "  Token: #{result['raw_token']}"
+  puts "  User:  #{result['user']}"
+  puts "  Role:  #{result['role']}"
+  puts "  Expires: #{result['expires_at'] || 'never'}"
+  puts ""
+  puts "  IMPORTANT: Store this token securely."
+  puts "  It will NOT be shown again."
+  puts ""
+  puts "  Configure in Cursor mcp.json:"
+  puts "  {"
+  puts "    \"mcpServers\": {"
+  puts "      \"kairos\": {"
+  puts "        \"url\": \"http://localhost:#{options[:port] || 8080}/mcp\","
+  puts "        \"headers\": {"
+  puts "          \"Authorization\": \"Bearer #{result['raw_token']}\""
+  puts "        }"
+  puts "      }"
+  puts "    }"
+  puts "  }"
+  puts ""
+  puts "=" * 60
+  exit
+end
+
+# Auto-initialize if data directory doesn't exist
+unless KairosMcp.initialized?
+  $stderr.puts "[KairosChain] Data directory not initialized at: #{KairosMcp.data_dir}"
+  $stderr.puts "[KairosChain] Run 'kairos-chain init' to set up, or auto-initializing..."
+  require 'kairos_mcp/initializer'
+  KairosMcp::Initializer.run(quiet: true)
+end
+
+# Handle --http (Streamable HTTP mode)
+if options[:http]
+  require 'kairos_mcp/http_server'
+
+  server = KairosMcp::HttpServer.new(
+    port: options[:port],
+    host: options[:host],
+    token_store_path: options[:token_store]
+  )
+  server.run
+else
+  # Default: stdio mode
+  require 'kairos_mcp/server'
+  KairosMcp::Server.run
+end

data/bin/kairos_mcp_server

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Backward-compatible shim: kairos_mcp_server -> kairos-chain
+#
+# This executable is kept for backward compatibility with existing
+# configurations (mcp.json, scripts, etc.). It delegates to the
+# main kairos-chain executable.
+
+$stderr.puts "[KairosChain] NOTE: 'kairos_mcp_server' is deprecated. Use 'kairos-chain' instead."
+
+load File.expand_path('kairos-chain', __dir__)

data/lib/kairos-chain.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Gem entrypoint for kairos-chain
+# Delegates to the internal KairosMcp module
+require_relative 'kairos_mcp'

data/lib/kairos_mcp/action_log.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+require 'fileutils'
+
+module KairosMcp
+  # ActionLog: Records actions for audit trail
+  #
+  # This class has been refactored to use the Storage backend abstraction.
+  # By default, it uses FileBackend (file-based storage).
+  # When SQLite is enabled, it uses SqliteBackend.
+  #
+  class ActionLog
+
+    class << self
+      # Record an action to the log
+      #
+      # @param action [String] The action performed
+      # @param skill_id [String, nil] The skill ID involved
+      # @param details [Hash, nil] Additional details
+      # @return [Boolean] Success status
+      def record(action:, skill_id: nil, details: nil)
+        entry = {
+          timestamp: Time.now.iso8601,
+          action: action,
+          skill_id: skill_id,
+          details: details
+        }
+
+        storage_backend.record_action(entry)
+      end
+
+      # Get action history
+      #
+      # @param limit [Integer] Maximum number of entries to return
+      # @return [Array<Hash>] Recent action log entries
+      def history(limit: 50)
+        storage_backend.action_history(limit: limit)
+      end
+
+      # Clear all action logs
+      #
+      # @return [Boolean] Success status
+      def clear!
+        storage_backend.clear_action_log!
+      end
+
+      # Get the storage backend type
+      # @return [Symbol] :file or :sqlite
+      def storage_type
+        storage_backend.backend_type
+      end
+
+      # Reset the storage backend (useful for testing)
+      def reset_backend!
+        @storage_backend = nil
+      end
+
+      # Set a custom storage backend (useful for testing or dependency injection)
+      # @param backend [Storage::Backend] The backend to use
+      def storage_backend=(backend)
+        @storage_backend = backend
+      end
+
+      private
+
+      def storage_backend
+        @storage_backend ||= default_storage_backend
+      end
+
+      def default_storage_backend
+        require_relative 'storage/backend'
+        Storage::Backend.default
+      end
+    end
+  end
+end

data/lib/kairos_mcp/admin/helpers.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require 'erb'
+require 'securerandom'
+require 'digest'
+
+module KairosMcp
+  module Admin
+    # Helpers: ERB template helpers for the admin UI
+    #
+    # Provides HTML escaping, template rendering, flash messages,
+    # CSRF protection, and session management utilities.
+    #
+    module Helpers
+      VIEWS_DIR = File.expand_path('views', __dir__)
+      STATIC_DIR = File.expand_path('static', __dir__)
+
+      # HTML-escape a string to prevent XSS
+      #
+      # @param text [String, nil] Raw text
+      # @return [String] HTML-escaped text
+      def h(text)
+        ERB::Util.html_escape(text.to_s)
+      end
+
+      # Render an ERB template
+      #
+      # @param template_name [String] Template file name (without .erb)
+      # @param layout [Boolean] Whether to wrap in layout
+      # @param locals [Hash] Local variables for the template
+      # @return [String] Rendered HTML
+      def render(template_name, layout: true, **locals)
+        template_path = File.join(VIEWS_DIR, "#{template_name}.erb")
+        template = ERB.new(File.read(template_path), trim_mode: '-')
+
+        # Make locals available as instance variables for ERB binding
+        b = binding
+        locals.each { |k, v| b.local_variable_set(k, v) }
+
+        content = template.result(b)
+
+        if layout
+          render_layout(content)
+        else
+          content
+        end
+      end
+
+      # Render a partial (no layout)
+      #
+      # @param partial_name [String] Partial file name (without .erb, with _prefix)
+      # @param locals [Hash] Local variables
+      # @return [String] Rendered HTML fragment
+      def render_partial(partial_name, **locals)
+        render("partials/#{partial_name}", layout: false, **locals)
+      end
+
+      # Wrap content in the shared layout
+      #
+      # @param content [String] Page content HTML
+      # @return [String] Full HTML page
+      def render_layout(content)
+        @content = content
+        layout_path = File.join(VIEWS_DIR, 'layout.erb')
+        layout_template = ERB.new(File.read(layout_path), trim_mode: '-')
+        layout_template.result(binding)
+      end
+
+      # Generate an HTML response
+      #
+      # @param status [Integer] HTTP status code
+      # @param body [String] HTML body
+      # @return [Array] Rack response triple
+      def html_response(status, body)
+        [status, { 'Content-Type' => 'text/html; charset=utf-8' }, [body]]
+      end
+
+      # Redirect response
+      #
+      # @param path [String] Redirect target
+      # @return [Array] Rack response triple
+      def redirect(path)
+        [302, { 'Location' => path }, []]
+      end
+
+      # Serve a static file
+      #
+      # @param filename [String] File name in static/ directory
+      # @return [Array] Rack response triple
+      def serve_static(filename)
+        filepath = File.join(STATIC_DIR, filename)
+        return [404, {}, ['Not found']] unless File.exist?(filepath)
+
+        content_type = case File.extname(filename)
+                       when '.css' then 'text/css'
+                       when '.js'  then 'application/javascript'
+                       when '.png' then 'image/png'
+                       when '.svg' then 'image/svg+xml'
+                       else 'application/octet-stream'
+                       end
+
+        [200, { 'Content-Type' => content_type, 'Cache-Control' => 'public, max-age=3600' },
+         [File.read(filepath)]]
+      end
+
+      # -----------------------------------------------------------------------
+      # Session Management
+      # -----------------------------------------------------------------------
+
+      SESSION_COOKIE = 'kairos_admin_session'
+      SESSION_SECRET = ENV['KAIROS_SESSION_SECRET'] || SecureRandom.hex(32)
+
+      # Encode a session value into a signed cookie
+      #
+      # @param data [Hash] Session data
+      # @return [String] Signed cookie value
+      def encode_session(data)
+        payload = JSON.generate(data)
+        encoded = [payload].pack('m0') # Base64 (no newlines)
+        signature = sign(encoded)
+        "#{encoded}--#{signature}"
+      end
+
+      # Decode and verify a signed session cookie
+      #
+      # @param cookie_value [String] Raw cookie value
+      # @return [Hash, nil] Session data or nil if invalid
+      def decode_session(cookie_value)
+        return nil unless cookie_value
+
+        encoded, signature = cookie_value.split('--', 2)
+        return nil unless encoded && signature
+        return nil unless secure_compare(sign(encoded), signature)
+
+        payload = encoded.unpack1('m0')
+        JSON.parse(payload, symbolize_names: true)
+      rescue StandardError
+        nil
+      end
+
+      # Extract session from Rack env
+      #
+      # @param env [Hash] Rack environment
+      # @return [Hash, nil] Session data
+      def get_session(env)
+        cookies = parse_cookies(env)
+        cookie_value = cookies[SESSION_COOKIE]
+        decode_session(cookie_value)
+      end
+
+      # Build Set-Cookie header for session
+      #
+      # @param data [Hash] Session data
+      # @return [String] Set-Cookie header value
+      def session_cookie(data)
+        value = encode_session(data)
+        "#{SESSION_COOKIE}=#{value}; Path=/admin; HttpOnly; SameSite=Strict"
+      end
+
+      # Build Set-Cookie header to clear session
+      #
+      # @return [String] Set-Cookie header value
+      def clear_session_cookie
+        "#{SESSION_COOKIE}=; Path=/admin; HttpOnly; SameSite=Strict; Max-Age=0"
+      end
+
+      # -----------------------------------------------------------------------
+      # CSRF Protection
+      # -----------------------------------------------------------------------
+
+      # Generate a CSRF token
+      #
+      # @return [String] CSRF token
+      def generate_csrf_token
+        SecureRandom.hex(32)
+      end
+
+      # Verify a CSRF token from form submission
+      #
+      # @param env [Hash] Rack environment
+      # @param session [Hash] Current session
+      # @return [Boolean] Whether CSRF token is valid
+      def valid_csrf?(env, session)
+        body = env['rack.input']&.read
+        env['rack.input']&.rewind
+        return false unless body
+
+        params = parse_form_body(body)
+        submitted_token = params['_csrf']
+        session_token = session&.dig(:csrf_token)
+
+        return false unless submitted_token && session_token
+
+        secure_compare(submitted_token, session_token)
+      end
+
+      # -----------------------------------------------------------------------
+      # Form/Cookie Parsing
+      # -----------------------------------------------------------------------
+
+      # Parse cookies from Rack env
+      #
+      # @param env [Hash] Rack environment
+      # @return [Hash] Cookie name → value
+      def parse_cookies(env)
+        cookie_header = env['HTTP_COOKIE'] || ''
+        cookie_header.split(';').each_with_object({}) do |pair, hash|
+          key, value = pair.strip.split('=', 2)
+          hash[key] = value if key
+        end
+      end
+
+      # Parse URL-encoded form body
+      #
+      # @param body [String] Form body
+      # @return [Hash] Parameter name → value
+      def parse_form_body(body)
+        body.split('&').each_with_object({}) do |pair, hash|
+          key, value = pair.split('=', 2)
+          hash[URI.decode_www_form_component(key)] = URI.decode_www_form_component(value || '')
+        end
+      end
+
+      # Parse query string
+      #
+      # @param env [Hash] Rack environment
+      # @return [Hash] Query parameters
+      def parse_query(env)
+        qs = env['QUERY_STRING'] || ''
+        parse_form_body(qs)
+      end
+
+      private
+
+      def sign(data)
+        Digest::SHA256.hexdigest("#{data}#{SESSION_SECRET}")
+      end
+
+      def secure_compare(a, b)
+        return false unless a.bytesize == b.bytesize
+
+        l = a.unpack("C#{a.bytesize}")
+        r = b.unpack("C#{b.bytesize}")
+        result = 0
+        l.zip(r) { |x, y| result |= x ^ y }
+        result.zero?
+      end
+    end
+  end
+end