rubik 0.1.0

data/lib/rubik/skills/manager.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require "monitor"
+require_relative "frontmatter"
+require_relative "storage"
+require_relative "registry"
+
+module Rubik
+  module Skills
+    # = Rubik::Skills::Manager
+    #
+    # Lifecycle facade of the Agent Skills subsystem (agentskills.io),
+    # provided as the +skill_manager+ coeffect (Composition.build →
+    # wire_runtime_context) and read per turn by the prompt builder.
+    #
+    # == AGENTS.md treatment
+    # A skill is DATA (frontmatter + markdown): never evaluated, no threads,
+    # no listeners — so the lifecycle-bearing unit is the Manager itself and
+    # the skills need no fibers. The Manager's single revertible effect is
+    # registering the +skill+ tool into the shared tool registry; that effect
+    # is opened on the Manager's OWN sub-context epoch (MCP::Manager
+    # pattern): enable/disable cycles extend/dispose the epoch, so inverses
+    # never stack across reloads (zero-restart rule, §1.A/§6) and disposal is
+    # local to the code that produced the effect (no detached teardown, §5).
+    class Manager
+      # Head-only body cap for the `skill` tool output. StepExecutor
+      # re-truncates every tool output on EITHER axis (tools.max_output_chars
+      # AND tools.max_output_lines) with head_tail, which would cut the middle
+      # out of ordered instructions — so Manager#body pre-truncates head-only
+      # below BOTH limits (see #body) and the read_file pointer is the
+      # recovery path for the omitted tail.
+      DEFAULT_MAX_BODY_CHARS = 8_000
+      # Lines the tool envelope adds around the body (3 header + truncation
+      # notice + recovery pointer) — headroom under the StepExecutor line
+      # budget (tools.max_output_lines).
+      BODY_LINE_ALLOWANCE = 8
+
+      attr_reader :config, :registry
+
+      def initialize(config:, root_dir:, home_dir:, runtime_context: nil)
+        @config = config
+        @root_dir = File.expand_path(root_dir.to_s)
+        @home_dir = home_dir ? File.expand_path(home_dir) : nil
+        @runtime_context = runtime_context
+        @registry = Registry.new
+        @epoch_context = nil
+        @monitor = Monitor.new
+        reload!
+      end
+
+      # Capability gate (MCP::Manager#enabled? precedent): disabling keeps
+      # the coeffect provided — retracting a fiber-gated coeffect would need
+      # a reactive reconcile — but empties the prompt index and closes the
+      # tool epoch.
+      def enabled?
+        fetch("skills.enabled", true) != false
+      end
+
+      def max_body_chars
+        (fetch("skills.max_body_chars", DEFAULT_MAX_BODY_CHARS) || DEFAULT_MAX_BODY_CHARS).to_i
+      end
+
+      # Residual line budget for the body, under the StepExecutor envelope.
+      def max_body_lines
+        raw = fetch("tools.max_output_lines", Rubik::Tools::Truncator::DEFAULT_MAX_LINES) ||
+              Rubik::Tools::Truncator::DEFAULT_MAX_LINES
+        [raw.to_i - BODY_LINE_ALLOWANCE, 1].max
+      end
+
+      def disabled_names
+        Array(fetch("skills.disabled", [])).map(&:to_s)
+      end
+
+      def all
+        return [] unless enabled?
+
+        @registry.all
+      end
+
+      def find(name)
+        return nil unless enabled?
+
+        @registry.find(name)
+      end
+
+      # Level-1 progressive-disclosure payload for the prompt layer (pure
+      # data, I/O-free downstream): name + description + scope only.
+      def prompt_index
+        all.map { |skill| { name: skill.name, description: skill.description, scope: skill.scope } }
+      end
+
+      # Level-2 read: the SKILL.md body, head-truncated below BOTH
+      # StepExecutor budgets (chars and lines) so the downstream head_tail
+      # pass can never amputate the middle; a read_file pointer covers the
+      # omitted tail — progressive disclosure doubles as the recovery path.
+      def body(name)
+        skill = find(name)
+        return nil unless skill
+
+        parsed = Frontmatter.parse(File.read(skill.path))
+        text = parsed[:body]
+        return safe(text) if text.bytesize <= max_body_chars && text.lines.size <= max_body_lines
+
+        trunc = Rubik::Tools::Truncator.truncate(text, max_chars: max_body_chars, max_lines: max_body_lines, strategy: :head_only)
+        "#{safe(trunc[:text])}Load the omitted tail with read_file: #{skill.path}\n"
+      rescue StandardError => e
+        Rubik::Platform.debug_warn("Failed to read skill '#{name}': #{e.class}: #{e.message}")
+        nil
+      end
+
+      # Re-discover from disk and atomically swap the snapshot. Per-skill
+      # validation problems are collected warnings (spec: skip invalid
+      # skills); a hard storage failure keeps the previous snapshot alive.
+      def reload!
+        result = storage.discover(disabled: disabled_names)
+        @registry.install(result)
+        result.issues.each { |issue| Rubik::Platform.debug_warn("skill #{issue.path}: #{issue.field} #{issue.message}") }
+        true
+      rescue StandardError => e
+        warn "[rubik] skills reload failed (previous snapshot kept): #{e.class}: #{e.message}"
+        false
+      end
+
+      # Validation issues from the last discovery (fatal rejections +
+      # warnings), for !skill output. Severity split via ValidationIssue#level.
+      def issues
+        @registry.issues
+      end
+
+      def status_summary
+        skills = all
+        {
+          enabled: enabled?,
+          total: skills.size,
+          by_scope: skills.group_by(&:scope).transform_values(&:size),
+          disabled: disabled_names,
+          skipped: @registry.issues.count(&:error?),
+          notes: @registry.issues.count(&:warning?),
+          shadowed: @registry.shadowed
+        }
+      end
+
+      # --- Epoch management: the revertible tool registration ---
+
+      # Registers the `skill` tool together with its unregister inverse on a
+      # dedicated sub-context. No-op when the epoch is already open or the
+      # subsystem is disabled. An activation failure disposes the partial
+      # sub-context (atomic rollback) and re-raises.
+      def open_epoch!(tool_registry)
+        @monitor.synchronize do
+          return if @epoch_context || !enabled? || tool_registry.nil?
+
+          context = @runtime_context&.extend || Rubik::Runtime::Context.new
+          begin
+            tool = Rubik::Tools::SkillTool.new(self, runtime_context: @runtime_context)
+            tool_registry.register(tool, origin: :builtin)
+            context.register_disposable { tool_registry.unregister(Rubik::Tools::SkillTool::NAME) }
+            @epoch_context = context
+          rescue StandardError
+            context.dispose
+            raise
+          end
+        end
+      end
+
+      # Disposes the epoch sub-context; the LIFO inverse unregisters the
+      # `skill` tool. Safe to call repeatedly.
+      def close_epoch!
+        @monitor.synchronize do
+          @epoch_context&.dispose
+          @epoch_context = nil
+        end
+      end
+
+      # ConfigWiring handler for skills.* knobs: re-read config, refresh the
+      # snapshot, and open/close the epoch only on an enabled flip.
+      def apply_config!(tool_registry: nil)
+        if enabled?
+          reload!
+          if tool_registry
+            open_epoch!(tool_registry)
+          else
+            Rubik::Platform.debug_warn("skills are enabled but no tool registry is available; the skill tool stays unregistered")
+          end
+        else
+          close_epoch!
+          reload!
+        end
+      end
+
+      def epoch_open?
+        @monitor.synchronize { !@epoch_context.nil? }
+      end
+
+      private
+
+      # Built per discovery (not memoized): skills.paths must be re-read from
+      # live config on every reload! so `!config set skills.paths [...]`
+      # takes effect without a restart.
+      def storage
+        Storage.new(
+          root_dir: @root_dir,
+          home_dir: @home_dir,
+          extra_paths: Array(fetch("skills.paths", []))
+        )
+      end
+
+      # fetch-with-default without the `|| default` idiom: an explicit
+      # config value of false/nil must survive (see Loop#safe_config hazard).
+      def fetch(key, default)
+        return default unless @config.respond_to?(:fetch)
+
+        @config.fetch(key, default)
+      end
+
+      # Encoding hygiene for File.read output reaching the model/history
+      # (byteslice truncation can split a multibyte character).
+      def safe(text)
+        Rubik::Platform.safe_utf8(text)
+      end
+    end
+  end
+end

data/lib/rubik/skills/registry.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module Rubik
+  module Skills
+    # In-memory immutable snapshot of discovered skills (name => Skill),
+    # Monitor-guarded. Registry#install swaps the whole snapshot atomically:
+    # readers observe either the complete old or the complete new index —
+    # that is the zero-downtime mechanism behind Manager#reload! (the system
+    # prompt is rebuilt per turn, so the next turn renders the fresh index).
+    class Registry
+      def initialize
+        @skills = {}.freeze
+        @shadowed = {}.freeze
+        @issues = [].freeze
+        @monitor = Monitor.new
+      end
+
+      # Precedence merge: the first occurrence of a name wins (Storage scans
+      # project > user > extra in that order); shadowed duplicates are
+      # recorded with their scopes and surfaced by `!skill list`.
+      def install(discovery)
+        merged = {}
+        shadowed = {}
+        discovery.skills.each do |skill|
+          if (winner = merged[skill.name])
+            entry = (shadowed[skill.name] ||= { winner_scope: winner.scope, loser_scopes: [] })
+            entry[:loser_scopes] << skill.scope
+          else
+            merged[skill.name] = skill
+          end
+        end
+        @monitor.synchronize do
+          @skills = merged.freeze
+          @shadowed = shadowed.transform_values(&:freeze).freeze
+          @issues = discovery.issues.freeze
+        end
+        self
+      end
+
+      def all
+        @monitor.synchronize { @skills.values.sort_by(&:name) }
+      end
+
+      def find(name)
+        @monitor.synchronize { @skills[name.to_s] }
+      end
+
+      def size
+        @monitor.synchronize { @skills.size }
+      end
+
+      def shadowed
+        @monitor.synchronize { @shadowed.dup }
+      end
+
+      # Validation issues from the last install (fatal rejections + warnings).
+      def issues
+        @monitor.synchronize { @issues.dup }
+      end
+    end
+  end
+end

data/lib/rubik/skills/skill.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Rubik
+  module Skills
+    # Immutable metadata record for one discovered skill (agentskills.io).
+    # Data only: it never holds the SKILL.md body (read on demand via
+    # Manager#body) and is never evaluated. One Struct instance per valid
+    # skill directory; +warnings+ carries non-fatal frontmatter deviations.
+    Skill = Struct.new(
+      :name, :description, :scope, :root,
+      :license, :compatibility, :metadata, :allowed_tools, :warnings,
+      keyword_init: true
+    ) do
+      # Absolute path of the skill manifest.
+      def path
+        File.join(root, "SKILL.md")
+      end
+
+      # Files bundled under the conventional auxiliary directories
+      # (level-3 progressive disclosure: the agent reads them on demand
+      # with read_file / run_command relative to the skill directory).
+      def auxiliary_files
+        AUXILIARY_DIRS.filter_map do |sub|
+          target = File.join(root, sub)
+          [sub, Dir.children(target).sort] if Dir.exist?(target)
+        end.to_h
+      rescue StandardError => e
+        Rubik::Platform.debug_warn("Failed to list auxiliary files for '#{name}': #{e.message}")
+        {}
+      end
+    end
+  end
+end

data/lib/rubik/skills/storage.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative "frontmatter"
+require_relative "skill"
+require_relative "validator"
+
+module Rubik
+  module Skills
+    DiscoveryResult = Struct.new(:skills, :issues, keyword_init: true)
+
+    # The only discovery/scan layer of the skills subsystem (body reads live
+    # in Manager#body, auxiliary listings in Skill#auxiliary_files). Pure
+    # scanner: no lifecycle, no caching, no writers — it returns every
+    # syntactically loadable skill (duplicates across scopes included);
+    # precedence resolution lives in Registry#install. Per-directory failures
+    # are collected as ValidationIssues and never abort the scan.
+    class Storage
+      attr_reader :project_root, :user_root, :extra_paths
+
+      def initialize(root_dir:, home_dir:, extra_paths: [])
+        @project_root = File.join(File.expand_path(root_dir.to_s), ".rubik", "skills")
+        @user_root = home_dir ? File.join(File.expand_path(home_dir), ".rubik", "skills") : nil
+        @extra_paths = Array(extra_paths).map { |p| File.expand_path(p.to_s) }
+      end
+
+      # Ordered discovery roots; earlier scopes win precedence in the
+      # Registry: project > user > extra paths (declaration order).
+      def scoped_roots
+        roots = [{ root: @project_root, scope: SCOPE_PROJECT }]
+        roots << { root: @user_root, scope: SCOPE_USER } if @user_root
+        @extra_paths.each { |path| roots << { root: path, scope: SCOPE_EXTRA } }
+        roots
+      end
+
+      # => DiscoveryResult(skills:, issues:)
+      def discover(disabled: [])
+        skills = []
+        issues = []
+        disabled_names = Array(disabled).map(&:to_s)
+
+        scoped_roots.each do |target|
+          next unless target[:root] && Dir.exist?(target[:root])
+
+          Dir.children(target[:root]).sort.each do |dir_name|
+            next if dir_name.start_with?(".")
+
+            dir = File.join(target[:root], dir_name)
+            next unless File.directory?(dir)
+
+            path = File.join(dir, "SKILL.md")
+            if disabled_names.include?(dir_name)
+              issues << ValidationIssue.new(path: path, field: :disabled, message: "skipped (listed in skills.disabled)", level: :warning)
+              next
+            end
+            unless File.file?(path)
+              issues << ValidationIssue.new(path: path, field: :skill_md, message: "missing SKILL.md", level: :error)
+              next
+            end
+
+            parsed = Frontmatter.parse(File.read(path))
+            skill, skill_issues = Validator.validate(
+              dir_name: dir_name, root: dir, scope: target[:scope], path: path, frontmatter: parsed[:frontmatter]
+            )
+            skills << skill if skill
+            issues.concat(skill_issues)
+          rescue Frontmatter::Error => e
+            issues << ValidationIssue.new(path: path, field: :frontmatter, message: e.message, level: :error)
+          rescue StandardError => e
+            issues << ValidationIssue.new(path: path, field: :io, message: "#{e.class}: #{e.message}", level: :error)
+          end
+        end
+
+        DiscoveryResult.new(skills: skills.freeze, issues: issues.freeze)
+      end
+    end
+  end
+end

data/lib/rubik/skills/validator.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Rubik
+  module Skills
+    # One collected validation problem. +level+ separates fatal rejections
+    # (:error — the skill is skipped) from non-fatal deviations (:warning —
+    # the skill is accepted and the note is surfaced by !skill).
+    ValidationIssue = Struct.new(:path, :field, :message, :level, keyword_init: true) do
+      def error?   = level == :error
+      def warning? = level == :warning
+    end
+
+    # agentskills.io frontmatter validation, spec-strict: fatal violations of
+    # the required fields (name, description) reject the skill; deviations in
+    # optional/experimental fields (metadata, allowed-tools, unknown keys)
+    # degrade to warnings. One bad skill never aborts a discovery scan.
+    class Validator
+      NAME_RE           = /\A[a-z0-9]+(?:-[a-z0-9]+)*\z/ # no lead/trail/double hyphen
+      MAX_NAME          = 64
+      MAX_DESCRIPTION   = 1024
+      MAX_COMPATIBILITY = 500
+      KNOWN_KEYS        = ["name", "description", "license", "compatibility", "metadata", "allowed-tools"].freeze
+
+      class << self
+        # => [Skill, Array<ValidationIssue>] — the Skill is nil when a fatal
+        # issue exists; the issue array carries fatal issues + warnings.
+        def validate(dir_name:, root:, scope:, path:, frontmatter:)
+          fatal = []
+          warnings = []
+
+          name = frontmatter["name"].to_s
+          description = frontmatter["description"].to_s.strip
+
+          fatal << build_issue(path, :name, "is required") if name.empty?
+          unless name.empty? || (name.length <= MAX_NAME && NAME_RE.match?(name))
+            fatal << build_issue(path, :name,
+                                 "'#{name}' must be 1-#{MAX_NAME} characters of [a-z0-9-], " \
+                                 "no leading/trailing/double hyphen")
+          end
+          fatal << build_issue(path, :name, "'#{name}' must equal its directory name '#{dir_name}'") if !name.empty? && name != dir_name
+
+          fatal << build_issue(path, :description, "is required (1-#{MAX_DESCRIPTION} characters)") if description.empty?
+          fatal << build_issue(path, :description, "exceeds #{MAX_DESCRIPTION} characters") if !description.empty? && description.length > MAX_DESCRIPTION
+
+          license = optional_string(frontmatter["license"], "license", path, warnings)
+          compatibility = optional_string(frontmatter["compatibility"], "compatibility", path, warnings)
+          fatal << build_issue(path, :compatibility, "exceeds #{MAX_COMPATIBILITY} characters") if compatibility.to_s.length > MAX_COMPATIBILITY
+
+          metadata = parse_metadata(frontmatter["metadata"], path, fatal)
+          allowed_tools = parse_allowed_tools(frontmatter["allowed-tools"], path, warnings)
+
+          (frontmatter.keys - KNOWN_KEYS).each do |key|
+            warnings << build_issue(path, key.to_sym, "unknown frontmatter key ignored", :warning)
+          end
+
+          issues = fatal + warnings
+          return [nil, issues] if fatal.any?
+
+          [Skill.new(
+            name: name, description: description, scope: scope, root: root,
+            license: license, compatibility: compatibility,
+            metadata: metadata.freeze, allowed_tools: allowed_tools.freeze,
+            warnings: warnings.freeze
+          ), issues]
+        end
+
+        private
+
+        # Fatal rejections default to :error; callers collecting warnings pass
+        # :warning explicitly.
+        def build_issue(path, field, message, level = :error)
+          ValidationIssue.new(path: path, field: field, message: message, level: level)
+        end
+
+        def optional_string(raw, key, path, warnings)
+          return nil if raw.nil?
+          return raw if raw.is_a?(String)
+
+          warnings << build_issue(path, key.to_sym, "ignored: must be a string", :warning)
+          nil
+        end
+
+        # Spec: "a map from string keys to string values" — any deviation is
+        # fatal (matches the skills-ref reference validator's strictness).
+        def parse_metadata(raw, path, fatal)
+          return {} if raw.nil?
+
+          unless raw.is_a?(Hash) && raw.keys.all?(String) && raw.values.all?(String)
+            fatal << build_issue(path, :metadata, "must be a map from string keys to string values")
+            return {}
+          end
+          raw
+        end
+
+        # Spec (experimental): "a space-separated string of pre-approved
+        # tools". Parsed and displayed only — never enforced. An Array form
+        # degrades to a warning (accepted for interoperability).
+        def parse_allowed_tools(raw, path, warnings)
+          case raw
+          when nil
+            []
+          when String
+            raw.split(/\s+/).reject(&:empty?)
+          when Array
+            warnings << build_issue(path, :"allowed-tools",
+                                    "given as a list; the spec declares a space-separated string", :warning)
+            raw.map(&:to_s)
+          else
+            warnings << build_issue(path, :"allowed-tools", "ignored: must be a space-separated string", :warning)
+            []
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubik/skills.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Rubik
+  module Skills
+    # Discovery scopes (precedence order: project > user > extra paths).
+    SCOPE_PROJECT = :project
+    SCOPE_USER    = :user
+    SCOPE_EXTRA   = :extra
+
+    # Conventional auxiliary directories of a skill (agentskills.io).
+    AUXILIARY_DIRS = ["scripts", "references", "assets"].freeze
+  end
+end
+
+require_relative "skills/skill"
+require_relative "skills/frontmatter"
+require_relative "skills/validator"
+require_relative "skills/storage"
+require_relative "skills/registry"
+require_relative "skills/manager"

data/lib/rubik/storage/folding.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Rubik
+  module Storage
+    # Arama katlamasının TEK evi (issue #99 bulgu 7): Unicode default
+    # downcase Türkçe I-sınıfını kapatamaz — "I" → "i" olur ama "ı"
+    # kendisi kalır ve "İ" iki karaktere ("i" + U+0307) açılır; böylece
+    # "ı"-lı sorgu ASCII "I" içeren gövdeyi asla bulamaz. Katlama sorguya
+    # ve samanlığa AYNI şekilde uygulanır: determinist, LLM'siz ve İngilizce
+    # metinde birebir nötr (ı/İ içermez).
+    module Folding
+      module_function
+
+      # "İ".downcase sonucu: "i" + U+0307 (birleşen nokta) — tek harfe indir.
+      COMBINING_DOT_ABOVE = "i\u0307"
+      DOTLESS_I = "\u0131"
+
+      def fold(text)
+        text.to_s.downcase.gsub(COMBINING_DOT_ABOVE, "i").gsub(DOTLESS_I, "i")
+      end
+    end
+  end
+end