igniter 0.5.0 → 0.5.1

data/packages/igniter-sdk/lib/igniter/sdk/tools/agent_bootstrap_tool.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Tools
+    class AgentBootstrapTool < Igniter::Tool
+      BOOTSTRAP_PROFILES = {
+        "esp32_bringup" => {
+          label: "ESP32 bring-up",
+          goals: %w[esp32 hardware embedded],
+          preferred_workflows: %w[platformio_esp32 arduino_esp32 ruby_workspace_dev],
+          checklist: [
+            "Verify the node can run the recommended firmware workflow.",
+            "Confirm the workspace services needed by the device are reachable.",
+            "Use serial monitor output to validate request/response flow.",
+            "Capture missing utilities or configuration gaps before flashing again."
+          ],
+          success_criteria: [
+            "A firmware toolchain is available.",
+            "The target workspace endpoint responds locally.",
+            "The device can complete one end-to-end request cycle."
+          ]
+        },
+        "cluster_debug" => {
+          label: "Cluster debug",
+          goals: %w[cluster debug ruby],
+          preferred_workflows: %w[ruby_workspace_dev local_sqlite_ops docker_compose_dev],
+          checklist: [
+            "Start the workspace in a debuggable local mode.",
+            "Inspect cluster ownership, events, and projections.",
+            "Check persistence tooling for local-first state.",
+            "Capture a minimal repro path before changing cluster logic."
+          ],
+          success_criteria: [
+            "The workspace can be started locally.",
+            "Event/projection debug surfaces are reachable.",
+            "Local data stores can be inspected."
+          ]
+        },
+        "local_ai_node" => {
+          label: "Local AI node",
+          goals: %w[ai inference local_llm media],
+          preferred_workflows: %w[local_llm_ollama media_pipeline python_sidecar ruby_workspace_dev],
+          checklist: [
+            "Verify local model or media tooling availability.",
+            "Check the node can run the relevant workspace services.",
+            "Confirm preprocessing or helper scripts are available.",
+            "Choose the smallest viable local inference loop first."
+          ],
+          success_criteria: [
+            "At least one AI or media workflow is available.",
+            "The inference-related workspace path can be run locally."
+          ]
+        },
+        "dashboard_dev" => {
+          label: "Dashboard development",
+          goals: %w[ui frontend ruby debug],
+          preferred_workflows: %w[ruby_workspace_dev node_frontend_tooling docker_compose_dev],
+          checklist: [
+            "Start the workspace app(s) needed by the dashboard.",
+            "Check whether node-based tooling is available for UI assets.",
+            "Use the local debug surfaces to inspect current state.",
+            "Prefer the simplest server-rendered loop before adding more tooling."
+          ],
+          success_criteria: [
+            "The dashboard app can start locally.",
+            "A suitable UI/tooling workflow is available."
+          ]
+        }
+      }.freeze
+
+      description "Turn a system snapshot into a concrete bootstrap plan for a named local development goal."
+
+      param :goal, type: :string, required: true,
+                   desc: "Bootstrap target such as esp32_bringup, cluster_debug, local_ai_node, or dashboard_dev."
+      param :include_discovery, type: :boolean, default: false,
+                                desc: "Include the underlying discovery snapshot in the returned plan."
+      param :include_unavailable, type: :boolean, default: true,
+                                  desc: "Include unavailable workflows and missing utilities in the selector output."
+
+      requires_capability :system_read
+
+      def call(goal:, include_discovery: false, include_unavailable: true)
+        profile = BOOTSTRAP_PROFILES.fetch(goal.to_s) do
+          raise ArgumentError, "Unknown bootstrap goal #{goal.inspect}. Known goals: #{BOOTSTRAP_PROFILES.keys.sort.join(", ")}"
+        end
+
+        selector = Igniter::Tools::LocalWorkflowSelectorTool.new.call(
+          goals: profile.fetch(:goals),
+          workflow_candidates: profile.fetch(:preferred_workflows),
+          include_discovery: include_discovery,
+          include_unavailable: include_unavailable
+        )
+
+        chosen = Array(selector[:recommended_workflows]).first
+
+        {
+          generated_at: Time.now.utc.iso8601,
+          goal: goal.to_s,
+          label: profile.fetch(:label),
+          selected_workflow: chosen,
+          recommended_workflows: selector.fetch(:recommended_workflows),
+          unavailable_workflows: selector.fetch(:unavailable_workflows, []),
+          bootstrap_steps: build_bootstrap_steps(profile, chosen),
+          checklist: profile.fetch(:checklist),
+          success_criteria: profile.fetch(:success_criteria),
+          suggested_commands: chosen ? Array(chosen[:recommended_commands]).first(3) : [],
+          notes: build_notes(profile, chosen, selector),
+          discovery: selector[:discovery]
+        }.compact
+      end
+
+      private
+
+      def build_bootstrap_steps(profile, chosen)
+        steps = [
+          "Start with the goal profile #{profile.fetch(:label).inspect}."
+        ]
+
+        if chosen
+          steps << "Use the workflow #{chosen.fetch(:label).inspect} because it is available on this node."
+          Array(chosen[:recommended_commands]).first(3).each do |command|
+            steps << "Run #{command.inspect}."
+          end
+        else
+          steps << "No preferred workflow is currently available on this node."
+          steps << "Inspect missing utilities and either install them or switch to another node."
+        end
+
+        steps.concat(profile.fetch(:checklist))
+      end
+
+      def build_notes(profile, chosen, selector)
+        notes = []
+
+        notes << "Preferred workflows were filtered to: #{profile.fetch(:preferred_workflows).join(", ")}."
+        if chosen
+          notes << "Selected workflow id: #{chosen.fetch(:id)}."
+        else
+          missing = Array(selector[:unavailable_workflows]).map do |workflow|
+            next if Array(workflow[:missing_utilities]).empty?
+
+            "#{workflow[:id]} missing #{workflow[:missing_utilities].join(", ")}"
+          end.compact
+          notes << "Unavailable workflow diagnostics: #{missing.join(" | ")}." unless missing.empty?
+        end
+
+        notes
+      end
+    end
+  end
+end

data/packages/igniter-sdk/lib/igniter/sdk/tools/local_workflow_selector_tool.rb

@@ -0,0 +1,269 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Tools
+    class LocalWorkflowSelectorTool < Igniter::Tool
+      WORKFLOW_CATALOG = [
+        {
+          id: "ruby_workspace_dev",
+          label: "Ruby workspace development",
+          goals: %w[general_dev ruby cluster],
+          required_utilities: %w[ruby bundle git],
+          optional_utilities: %w[rake rspec sqlite3 rg],
+          recommended_commands: [
+            "bundle install",
+            "bundle exec rspec",
+            "bin/dev"
+          ],
+          rationale: "Good default for developing Igniter workspaces and running specs locally."
+        },
+        {
+          id: "platformio_esp32",
+          label: "ESP32 firmware development with PlatformIO",
+          goals: %w[esp32 hardware embedded],
+          required_utilities: %w[pio],
+          optional_utilities: %w[python3 git],
+          recommended_commands: [
+            "pio run",
+            "pio run -t upload",
+            "pio device monitor"
+          ],
+          rationale: "Best fit for iterative ESP32 bring-up, firmware flashing, and serial debugging."
+        },
+        {
+          id: "arduino_esp32",
+          label: "ESP32 CLI flashing with Arduino/esptool",
+          goals: %w[esp32 hardware embedded recovery],
+          required_utilities: [],
+          alternative_required_sets: [%w[arduino-cli], %w[esptool.py]],
+          optional_utilities: %w[python3],
+          recommended_commands: [
+            "arduino-cli compile",
+            "arduino-cli upload",
+            "esptool.py --chip esp32 ..."
+          ],
+          rationale: "Useful as an alternative or recovery path when PlatformIO is not available."
+        },
+        {
+          id: "docker_compose_dev",
+          label: "Containerized local stack",
+          goals: %w[containers deploy cluster],
+          required_utilities: %w[docker],
+          optional_utilities: %w[docker-compose],
+          recommended_commands: [
+            "bin/start --write-compose",
+            "docker compose up",
+            "docker compose logs -f"
+          ],
+          rationale: "Useful when the workspace should run as a local multi-process stack with container boundaries."
+        },
+        {
+          id: "local_llm_ollama",
+          label: "Local LLM via Ollama",
+          goals: %w[ai inference local_llm],
+          required_utilities: %w[ollama],
+          optional_utilities: %w[curl],
+          recommended_commands: [
+            "ollama serve",
+            "ollama pull <model>"
+          ],
+          rationale: "Enables local inference experiments without a hosted API."
+        },
+        {
+          id: "media_pipeline",
+          label: "Audio/video/media preprocessing",
+          goals: %w[media audio video asr tts],
+          required_utilities: %w[ffmpeg],
+          optional_utilities: %w[python3],
+          recommended_commands: [
+            "ffmpeg -i input.wav output.mp3"
+          ],
+          rationale: "Useful for audio normalization, transcoding, and dataset preparation."
+        },
+        {
+          id: "local_sqlite_ops",
+          label: "Local SQLite inspection and debugging",
+          goals: %w[data sqlite debug],
+          required_utilities: %w[sqlite3],
+          optional_utilities: %w[rg],
+          recommended_commands: [
+            "sqlite3 var/app.sqlite3",
+            ".tables"
+          ],
+          rationale: "Helpful for local-first app data inspection and debugging."
+        },
+        {
+          id: "python_sidecar",
+          label: "Python sidecar tooling",
+          goals: %w[python scripts data],
+          required_utilities: %w[python3],
+          optional_utilities: %w[pip3],
+          recommended_commands: [
+            "python3 script.py",
+            "pip3 install <package>"
+          ],
+          rationale: "Useful when the node needs lightweight scripting or data-processing helpers."
+        },
+        {
+          id: "node_frontend_tooling",
+          label: "Node-based frontend or tooling workflow",
+          goals: %w[node frontend ui tooling],
+          required_utilities: %w[node],
+          optional_utilities: %w[npm pnpm yarn],
+          recommended_commands: [
+            "npm install",
+            "npm run dev"
+          ],
+          rationale: "Useful for UI plugins, build tooling, or frontend assets."
+        }
+      ].freeze
+
+      description "Use a local system snapshot to recommend which development or runtime workflows are actually available on this machine."
+
+      param :goals, type: :array, default: [],
+                    desc: "Optional goal tags such as esp32, cluster, ai, media, sqlite, frontend."
+      param :include_discovery, type: :boolean, default: true,
+                                desc: "Include the underlying system discovery snapshot in the result."
+      param :include_unavailable, type: :boolean, default: true,
+                                  desc: "Include workflows that are currently unavailable along with missing utilities."
+      param :workflow_candidates, type: :array, default: [],
+                                  desc: "Optional workflow ids to limit evaluation."
+      param :scan_path_entries, type: :boolean, default: false,
+                                desc: "Whether to include a discovered executable listing in the underlying discovery step."
+      param :path_entry_limit, type: :integer, default: 100,
+                               desc: "Maximum number of PATH executables to include when scanning."
+
+      requires_capability :system_read
+
+      def call(goals: [], include_discovery: true, include_unavailable: true, workflow_candidates: [],
+               scan_path_entries: false, path_entry_limit: 100)
+        discovery = Igniter::Tools::SystemDiscoveryTool.new.call(
+          scan_path_entries: scan_path_entries,
+          path_entry_limit: path_entry_limit
+        )
+
+        goal_list = Array(goals).map(&:to_s).reject(&:empty?)
+        selected_workflows = catalog_for(workflow_candidates, goal_list)
+        evaluated = evaluate_workflows(selected_workflows, discovery, include_unavailable: include_unavailable)
+
+        {
+          generated_at: Time.now.utc.iso8601,
+          goals: goal_list,
+          available_workflows: evaluated.select { |workflow| workflow[:available] },
+          unavailable_workflows: include_unavailable ? evaluated.reject { |workflow| workflow[:available] } : [],
+          recommended_workflows: recommended_workflows(evaluated, goal_list),
+          suggested_next_steps: suggested_next_steps(evaluated, goal_list),
+          discovery: include_discovery ? discovery : nil
+        }.compact
+      end
+
+      private
+
+      def catalog_for(workflow_candidates, goals)
+        workflows = if Array(workflow_candidates).empty?
+                      WORKFLOW_CATALOG
+                    else
+                      requested = Array(workflow_candidates).map(&:to_s)
+                      WORKFLOW_CATALOG.select { |workflow| requested.include?(workflow.fetch(:id)) }
+                    end
+
+        return workflows if goals.empty?
+
+        tagged = workflows.select do |workflow|
+          (workflow.fetch(:goals, []) & goals).any?
+        end
+
+        tagged.empty? ? workflows : tagged
+      end
+
+      def evaluate_workflows(workflows, discovery, include_unavailable:)
+        utilities = Array(discovery.dig(:paths, :utility_candidates))
+        availability = utilities.each_with_object({}) do |entry, memo|
+          memo[entry.fetch(:name)] = entry.fetch(:present)
+        end
+
+        workflows.each_with_object([]) do |workflow, memo|
+          evaluated = evaluate_workflow(workflow, availability)
+          next if !include_unavailable && !evaluated[:available]
+
+          memo << evaluated
+        end
+      end
+
+      def evaluate_workflow(workflow, availability)
+        required = workflow.fetch(:required_utilities, [])
+        optional = workflow.fetch(:optional_utilities, [])
+        alternatives = workflow.fetch(:alternative_required_sets, [])
+
+        missing_required = required.reject { |utility| availability[utility] }
+        alternative_satisfied = alternatives.empty? || alternatives.any? do |set|
+          Array(set).all? { |utility| availability[utility] }
+        end
+
+        available = missing_required.empty? && alternative_satisfied
+        missing_alternatives = if alternative_satisfied || alternatives.empty?
+                                 []
+                               else
+                                 alternatives.map { |set| Array(set).join(" + ") }
+                               end
+
+        {
+          id: workflow.fetch(:id),
+          label: workflow.fetch(:label),
+          goals: workflow.fetch(:goals, []),
+          available: available,
+          required_utilities: required,
+          optional_utilities: optional,
+          missing_utilities: missing_required,
+          alternative_required_sets: alternatives,
+          missing_alternative_sets: missing_alternatives,
+          available_optional_utilities: optional.select { |utility| availability[utility] },
+          recommended_commands: workflow.fetch(:recommended_commands, []),
+          rationale: workflow.fetch(:rationale),
+          score: workflow_score(workflow, availability)
+        }
+      end
+
+      def workflow_score(workflow, availability)
+        required = workflow.fetch(:required_utilities, [])
+        optional = workflow.fetch(:optional_utilities, [])
+        available_required = required.count { |utility| availability[utility] }
+        available_optional = optional.count { |utility| availability[utility] }
+        base = available_required * 10
+        base += available_optional
+
+        if workflow.fetch(:alternative_required_sets, []).any?
+          satisfied = workflow.fetch(:alternative_required_sets).any? do |set|
+            Array(set).all? { |utility| availability[utility] }
+          end
+          base += 8 if satisfied
+        end
+
+        base
+      end
+
+      def recommended_workflows(evaluated, goals)
+        list = evaluated.select { |workflow| workflow[:available] }
+        list = list.sort_by { |workflow| [-goal_overlap(workflow, goals), -workflow[:score], workflow[:id]] }
+        list.first(3)
+      end
+
+      def suggested_next_steps(evaluated, goals)
+        available = recommended_workflows(evaluated, goals)
+        return ["Run system discovery only; no matching workflow was available on this node."] if available.empty?
+
+        available.flat_map do |workflow|
+          workflow.fetch(:recommended_commands, []).first(2).map do |command|
+            "#{workflow[:label]}: #{command}"
+          end
+        end
+      end
+
+      def goal_overlap(workflow, goals)
+        return 0 if goals.empty?
+
+        (Array(workflow[:goals]) & goals).size
+      end
+    end
+  end
+end

data/packages/igniter-sdk/lib/igniter/sdk/tools/system_discovery_tool.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require "etc"
+require "rbconfig"
+require "socket"
+require "time"
+
+module Igniter
+  module Tools
+    class SystemDiscoveryTool < Igniter::Tool
+      DEFAULT_UTILITY_CANDIDATES = %w[
+        ruby
+        bundle
+        rake
+        rspec
+        git
+        curl
+        wget
+        rg
+        fd
+        jq
+        sqlite3
+        redis-cli
+        psql
+        python3
+        pip3
+        node
+        npm
+        yarn
+        pnpm
+        docker
+        docker-compose
+        ffmpeg
+        ollama
+        pio
+        arduino-cli
+        esptool.py
+        make
+        gcc
+        clang
+      ].freeze
+
+      SAFE_ENV_ALLOWLIST = %w[
+        HOME
+        USER
+        SHELL
+        LANG
+        TERM
+        PATH
+        RUBY_ENGINE
+        RUBY_VERSION
+        BUNDLE_GEMFILE
+        GEM_HOME
+        GEM_PATH
+        RBENV_VERSION
+        ASDF_DIR
+        NODENV_VERSION
+        PYENV_VERSION
+      ].freeze
+
+      description "Inspect the current host environment and return a structured snapshot of the system, runtime, PATH, and available utilities."
+
+      param :include_environment, type: :boolean, default: false,
+                                  desc: "Include a filtered environment variable snapshot."
+      param :environment_keys, type: :array, default: SAFE_ENV_ALLOWLIST,
+                               desc: "Environment variable names to include when include_environment is true."
+      param :utility_candidates, type: :array, default: DEFAULT_UTILITY_CANDIDATES,
+                                 desc: "Specific utility names to probe in PATH."
+      param :scan_path_entries, type: :boolean, default: true,
+                                desc: "Whether to scan PATH directories and list executable names."
+      param :path_entry_limit, type: :integer, default: 250,
+                               desc: "Maximum number of discovered PATH executables to return."
+
+      requires_capability :system_read
+
+      def call(include_environment: false, environment_keys: SAFE_ENV_ALLOWLIST,
+               utility_candidates: DEFAULT_UTILITY_CANDIDATES, scan_path_entries: true, path_entry_limit: 250)
+        {
+          generated_at: Time.now.utc.iso8601,
+          host: host_snapshot,
+          runtime: runtime_snapshot,
+          paths: path_snapshot(
+            utility_candidates: utility_candidates,
+            scan_path_entries: scan_path_entries,
+            path_entry_limit: path_entry_limit
+          ),
+          environment: include_environment ? environment_snapshot(environment_keys) : nil
+        }.compact
+      end
+
+      private
+
+      def host_snapshot
+        {
+          hostname: safe_hostname,
+          platform: RUBY_PLATFORM,
+          os: RbConfig::CONFIG["host_os"],
+          cpu: RbConfig::CONFIG["host_cpu"],
+          user: safe_user,
+          home: ENV["HOME"],
+          shell: ENV["SHELL"]
+        }.compact
+      end
+
+      def runtime_snapshot
+        {
+          ruby: {
+            version: RUBY_VERSION,
+            engine: defined?(RUBY_ENGINE) ? RUBY_ENGINE : "ruby",
+            platform: RUBY_PLATFORM,
+            executable: RbConfig.ruby
+          },
+          process: {
+            pid: Process.pid,
+            cwd: Dir.pwd
+          }
+        }
+      end
+
+      def path_snapshot(utility_candidates:, scan_path_entries:, path_entry_limit:)
+        entries = ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).reject(&:empty?)
+
+        {
+          path_entries: entries,
+          utility_candidates: resolve_candidates(Array(utility_candidates)),
+          discovered_executables: scan_path_entries ? scan_executables(entries, limit: path_entry_limit.to_i) : []
+        }
+      end
+
+      def environment_snapshot(keys)
+        Array(keys).each_with_object({}) do |key, memo|
+          name = key.to_s
+          next unless ENV.key?(name)
+
+          memo[name] = ENV[name]
+        end
+      end
+
+      def resolve_candidates(candidates)
+        candidates.map do |name|
+          {
+            name: name.to_s,
+            present: !find_executable(name).nil?,
+            path: find_executable(name)
+          }
+        end
+      end
+
+      def scan_executables(path_entries, limit:)
+        discovered = path_entries.each_with_object([]) do |entry, memo|
+          break memo if memo.size >= limit
+          next unless File.directory?(entry)
+
+          Dir.children(entry).sort.each do |child|
+            full = File.join(entry, child)
+            next unless File.file?(full)
+            next unless File.executable?(full)
+
+            memo << child
+            break if memo.size >= limit
+          end
+        rescue SystemCallError
+          next
+        end
+
+        discovered.uniq.sort
+      end
+
+      def find_executable(name)
+        target = name.to_s
+        return nil if target.empty?
+
+        ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).each do |entry|
+          next if entry.to_s.empty?
+
+          candidate = File.join(entry, target)
+          return candidate if File.file?(candidate) && File.executable?(candidate)
+        rescue SystemCallError
+          next
+        end
+
+        nil
+      end
+
+      def safe_hostname
+        Socket.gethostname
+      rescue SocketError
+        nil
+      end
+
+      def safe_user
+        Etc.getlogin || Etc.passwd.name
+      rescue StandardError
+        ENV["USER"]
+      end
+    end
+  end
+end

data/packages/igniter-sdk/lib/igniter/sdk/tools.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "igniter/core"
+require_relative "tools/system_discovery_tool"
+require_relative "tools/local_workflow_selector_tool"
+require_relative "tools/agent_bootstrap_tool"
+
+module Igniter
+end