superkick 0.1.0

data/lib/superkick.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+# Standard library
+require "fileutils"
+require "json"
+require "logger"
+require "socket"
+require "base64"
+require "time"
+require "yaml"
+require "liquid"
+require "faraday"
+require "faraday/multipart"
+require "timeout"
+require "shellwords"
+
+# Core (dependency-free)
+require_relative "superkick/registry"
+require_relative "superkick/version"
+require_relative "superkick/drop"
+require_relative "superkick/drops"
+require_relative "superkick/configuration"
+require_relative "superkick/injection_guard"
+require_relative "superkick/connection"
+require_relative "superkick/process_runner"
+
+# Agent runtimes (process management backends)
+require_relative "superkick/agent/runtimes"
+
+# Persistence
+require_relative "superkick/repository_source"
+require_relative "superkick/local/repository_source"
+require_relative "superkick/agent"
+require_relative "superkick/environment_executor"
+require_relative "superkick/agent_store"
+require_relative "superkick/team/log"
+require_relative "superkick/team/log_store"
+require_relative "superkick/team/artifact_store"
+
+# Client registry (shared by Control, Buffer, Attach)
+require_relative "superkick/client_registry"
+
+# Control plane
+require_relative "superkick/control/reply"
+require_relative "superkick/control/client"
+require_relative "superkick/control/server"
+
+# Buffer (agent↔server data plane)
+require_relative "superkick/buffer/client"
+require_relative "superkick/buffer/server"
+
+# Pty
+require_relative "superkick/input_buffer"
+require_relative "superkick/output_logger"
+require_relative "superkick/session_recorder"
+require_relative "superkick/attach/protocol"
+require_relative "superkick/history_buffer"
+require_relative "superkick/attach/server"
+require_relative "superkick/attach/client"
+
+# Hosted mode — base class + all hosted overlays (after base classes they inherit from)
+require_relative "superkick/hosted/bridge"
+require_relative "superkick/hosted/control/client"
+require_relative "superkick/hosted/buffer/client"
+require_relative "superkick/hosted/buffer/relay"
+require_relative "superkick/hosted/buffer/relay_store"
+require_relative "superkick/hosted/buffer/bridge"
+require_relative "superkick/hosted/attach/client"
+require_relative "superkick/hosted/attach/relay"
+require_relative "superkick/hosted/attach/relay_store"
+require_relative "superkick/hosted/attach/bridge"
+require_relative "superkick/pty_proxy"
+
+# Injection queue + injection
+require_relative "superkick/injection_queue"
+require_relative "superkick/injector"
+require_relative "superkick/inject_handler"
+require_relative "superkick/template_filters"
+require_relative "superkick/template_renderer"
+require_relative "superkick/notifier_template"
+
+# Notifiers (post-injection user notifications)
+require_relative "superkick/notifier_state_store"
+require_relative "superkick/notifier"
+require_relative "superkick/notification_dispatcher"
+require_relative "superkick/notifiers/terminal_bell"
+require_relative "superkick/notifiers/command"
+require_relative "superkick/team/log_notifier"
+
+# Polling base class + monitor and spawner base classes
+require_relative "superkick/poller"
+require_relative "superkick/monitor"
+require_relative "superkick/team/log_entry_drop"
+require_relative "superkick/team/log_monitor"
+require_relative "superkick/spawner"
+require_relative "superkick/supervisor"
+
+# Version control adapters
+require_relative "superkick/version_control"
+
+# Goals (spawned agent completion checks)
+require_relative "superkick/goal"
+require_relative "superkick/goals/agent_exit"
+require_relative "superkick/goals/command"
+require_relative "superkick/goals/agent_signal"
+
+# Cost tracking
+require_relative "superkick/cost_accumulator"
+require_relative "superkick/cost_extractor"
+require_relative "superkick/cost_poller"
+require_relative "superkick/budget_checker"
+
+# Spawner infrastructure
+require_relative "superkick/spawn/handler"
+require_relative "superkick/spawn/injector"
+require_relative "superkick/spawn/agent_spawner"
+require_relative "superkick/spawn/approval_store"
+require_relative "superkick/spawn/workflow_validator"
+require_relative "superkick/spawn/workflow_executor"
+
+# Integrations (monitors, spawners, notifiers, runtimes)
+require_relative "superkick/integrations/git"
+require_relative "superkick/integrations/docker"
+require_relative "superkick/integrations/github"
+require_relative "superkick/integrations/shell"
+require_relative "superkick/integrations/circleci"
+require_relative "superkick/integrations/shortcut"
+require_relative "superkick/integrations/bugsnag"
+require_relative "superkick/integrations/slack"
+require_relative "superkick/integrations/datadog"
+require_relative "superkick/integrations/honeybadger"
+
+# Drivers — loads Driver base class then all built-in driver subclasses.
+require_relative "superkick/drivers"
+require_relative "superkick/driver/profile_source"
+
+# Config loading
+require_relative "superkick/yaml_config"
+
+# Setup wizard
+require_relative "superkick/setup"
+
+# MCP server + CLI
+require_relative "superkick/mcp_server"
+require_relative "superkick/hosted/mcp_proxy"
+require_relative "superkick/server"
+require_relative "superkick/cli"
+
+module Superkick
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+    end
+
+    def logger
+      @logger ||= begin
+        l = Logger.new($stderr)
+        l.level = config.log_level
+        l.formatter = proc do |severity, datetime, progname, msg|
+          "#{datetime.strftime("%Y-%m-%d %H:%M:%S")} #{severity.ljust(5)} [#{progname}] #{msg}\n"
+        end
+        l
+      end
+    end
+
+    attr_writer :logger
+
+    # The active driver instance, set by Superkick.use.
+    attr_reader :driver
+
+    # Look up a driver class by name, instantiate it with opts, and store it.
+    def use(driver_name, **opts)
+      klass = Driver.lookup(driver_name)
+      @driver = klass.new(**opts)
+    end
+
+    alias_method :configure_for, :use
+
+    # Load YAML config then Ruby config from base_dir.
+    def load_config!
+      yaml_path = File.join(config.base_dir, "config.yml")
+      rb_path = File.join(config.base_dir, "config.rb")
+
+      YamlConfig.load!(yaml_path) if File.exist?(yaml_path)
+      load(rb_path) if File.exist?(rb_path)
+    end
+
+    def reset_config!
+      @config = Configuration.new
+      @driver = nil
+      TemplateRenderer.reset_environments!
+    end
+  end
+end

data/plan.md

@@ -0,0 +1,267 @@
+# Plan: `superkick setup` Command
+
+## Overview
+
+Add an interactive `superkick setup` command that walks first-time users through creating a well-documented `config.yml`, configuring MCP, and installing shell completions. Each integration (monitor, spawner, notifier, repository source) provides its own YAML config template so the generated config is self-documenting with comments, reasonable defaults, and `env()` ERB helpers for secrets.
+
+Uses the [`tty-prompt`](https://github.com/piotrmurach/tty-prompt) gem for interactive multi-select menus, single-select driver choice, and yes/no prompts.
+
+## Design
+
+### Config Template System
+
+Each extensibility point (Monitor, Spawner, Notifier, RepositorySource) gains an optional `self.setup_config` class method that returns a YAML string snippet. This is raw YAML text (not a hash) so it can include comments. The setup command concatenates selected snippets into the final `config.yml`.
+
+```ruby
+# Example: on Integrations::GitHub::Monitor
+def self.setup_config
+  <<~YAML
+    github:
+      token: <%%= env("GITHUB_TOKEN") %>
+      # repo and branch are auto-detected from git remote.
+      # Uncomment to override:
+      # repo: org/repo
+      # branch: main
+  YAML
+end
+```
+
+**Why raw YAML strings instead of structured hashes?** Because comments are the whole point — they make the generated config self-documenting. `YAML.dump` cannot produce comments. Each integration knows its own config best and can provide contextual help inline.
+
+The base classes (`Poller`, `Notifier`, `RepositorySource`) define `self.setup_config = nil` as the default. Integrations that want to participate in setup override it.
+
+### Gate: `setup_label`
+
+Each base class also gains `self.setup_label = nil`. This returns a short human-readable name for the setup menu (e.g., `"GitHub"`, `"CircleCI"`, `"Slack"`). When nil, the integration doesn't appear in setup. When both `setup_config` and `setup_label` are defined, the integration is selectable.
+
+This keeps things simple: internal-only integrations like `Slack::ThreadMonitor` (auto-attached by spawner) just don't define `setup_label`.
+
+### Setup Flow
+
+1. **Welcome** — brief explanation of what setup does
+2. **Check for existing config** — if `config.yml` exists, ask to overwrite or abort
+3. **Choose driver** — auto-detect installed AI CLIs from `$PATH`, present as `tty-prompt` `select` menu with detected ones marked
+4. **Select monitors** — `tty-prompt` `multi_select` of all monitors with `setup_label`. Each shows label + first line of `description`
+5. **Select spawners** — same pattern. Skip section entirely if user selects none (spawners are advanced)
+6. **Select notifications** — same pattern. Default pre-selects `terminal_bell`
+7. **Select repository sources** — same pattern. Skip if none
+8. **Generate `config.yml`** — assemble from driver + selected templates + commented-out tuning section
+9. **Install MCP** — call `driver.install_mcp(exe_path:)`
+10. **Shell completions** — offer to print the `eval` line for their shell
+11. **Print next steps** — `superkick server start -d` then `superkick agent start`
+
+### Generated Config Structure
+
+```yaml
+# Superkick configuration
+# Generated by `superkick setup` on 2026-03-21
+# Docs: https://github.com/admtnnr/superkick
+
+driver: claude_code
+
+# ── Monitors ─────────────────────────────────────────────
+# Monitors watch external services and inject context into your AI CLI.
+# Config values like repo and branch are auto-detected at runtime.
+monitors:
+  github:
+    token: <%%= env("GITHUB_TOKEN") %>
+    # repo and branch are auto-detected from git remote.
+    # Uncomment to override:
+    # repo: org/repo
+    # branch: main
+
+  disk_check:
+    type: shell
+    command: .superkick/shell/disk-check
+    # timeout: 30
+    # report_success: false
+
+# ── Notifications ────────────────────────────────────────
+# Notifications fire after injections and agent lifecycle events.
+notifications:
+  - type: terminal_bell
+
+# ── Settings ─────────────────────────────────────────────
+# Uncomment to customize. Defaults are shown.
+# superkick:
+#   poll_interval: 30        # seconds between monitor ticks
+#   idle_threshold: 5.0      # seconds CLI must be idle before injection
+#   log_level: info          # debug, info, warn, error
+```
+
+Sections are only included when the user selected items for that category. The settings section is always appended (commented out).
+
+## Implementation Steps
+
+### Step 1: Add `tty-prompt` dependency
+
+Add `spec.add_dependency "tty-prompt", "~> 0.23"` to `superkick.gemspec`.
+
+### Step 2: Add `self.setup_config` and `self.setup_label` to base classes
+
+Add default `nil` implementations to:
+- `Superkick::Poller` (covers Monitor and Spawner via inheritance)
+- `Superkick::Notifier`
+- `Superkick::RepositorySource`
+
+### Step 3: Add `setup_config` and `setup_label` to built-in integrations
+
+Each snippet uses `<%= env("...") %>` for secrets, shows required keys uncommented, optional keys commented with defaults, and inline help comments.
+
+**Monitors:**
+- `Integrations::GitHub::Monitor` — label: `"GitHub"`, token via env, repo/branch commented (auto-detected)
+- `Integrations::CircleCI::Monitor` — label: `"CircleCI"`, token via env, project_slug/branch commented (auto-detected)
+- `Integrations::Shortcut::Monitor` — label: `"Shortcut"`, token via env, story_id commented (auto-detected from branch)
+- `Integrations::Shell::Monitor` — label: `"Shell"`, command placeholder, timeout/report_success commented
+- `Integrations::Datadog::AlertMonitor` — label: `"Datadog Alert"`, monitor_id placeholder, api_key/app_key via env
+- (Skip `Slack::ThreadMonitor` — auto-attached by spawner, not user-configured)
+
+**Spawners:**
+- `Integrations::GitHub::IssueSpawner` — label: `"GitHub Issues"`, repo, token, labels, goal config
+- `Integrations::GitHub::CheckFailedSpawner` — label: `"GitHub Check Failures"`, repo, branches, token
+- `Integrations::Shortcut::Spawner` — label: `"Shortcut"`, query, token
+- `Integrations::Slack::Spawner` — label: `"Slack"`, channel, token
+- `Integrations::Bugsnag::Spawner` — label: `"Bugsnag"`, project_id, token
+- `Integrations::Datadog::Spawner` — label: `"Datadog Errors"`, service, environment, api_key/app_key
+- `Integrations::Datadog::AlertSpawner` — label: `"Datadog Alerts"`, tags, statuses, api_key/app_key
+- `Integrations::Honeybadger::Spawner` — label: `"Honeybadger"`, project_id, token
+
+**Notifiers:**
+- `Notifiers::TerminalBell` — label: `"Terminal Bell"`, just `type: terminal_bell`
+- `Notifiers::Command` — label: `"Command"`, run command with example
+- `Integrations::Slack::Notifier` — label: `"Slack"`, webhook_url or token+channel
+- `Integrations::Datadog::Notifier` — label: `"Datadog"`, statsd_host, statsd_port, prefix
+- `Integrations::Honeybadger::Notifier` — label: `"Honeybadger"`, api_key
+
+**Repository Sources:**
+- `Local::RepositorySource` — label: `"Local"`, path example
+- `Integrations::Git::RepositorySource` — label: `"Git URL"`, url example
+- `Integrations::GitHub::OrganizationRepositorySource` — label: `"GitHub Organization"`, organization, token
+
+### Step 4: Implement `Superkick::Setup` class
+
+Create `lib/superkick/setup.rb`. This class encapsulates config generation logic, keeping it separate from the Thor command for testability.
+
+```ruby
+module Superkick
+  class Setup
+    def initialize(base_dir:)
+
+    # Returns Array of { name:, cli_command:, installed: } for each registered driver
+    def detect_drivers
+
+    # Returns Array of { type:, label:, description: } for each monitor with setup_label
+    def available_monitors
+
+    # Same pattern for spawners, notifiers, repository_sources
+    def available_spawners
+    def available_notifiers
+    def available_repository_sources
+
+    # Assembles the final config.yml string from selected components
+    # driver: Symbol, monitors/spawners/notifiers/repository_sources: Array of type Symbols
+    def generate_config(driver:, monitors: [], spawners: [], notifiers: [], repository_sources: [])
+  end
+end
+```
+
+`generate_config` builds the YAML string by:
+1. Writing header comment with timestamp
+2. Writing `driver:` line
+3. For each section (monitors, spawners, etc.), writing section header comment + concatenated `setup_config` snippets from selected types, indented appropriately under the YAML key
+4. Appending the commented-out settings section
+
+### Step 5: Implement `CLI::Setup` Thor subcommand
+
+Create `lib/superkick/cli/setup.rb`. Single default command `start` that drives the interactive flow.
+
+Uses `TTY::Prompt` for all interactive prompts:
+- `prompt.select("Which AI CLI driver?", choices)` — for driver
+- `prompt.multi_select("Which monitors?", choices)` — for monitors, spawners, etc.
+- `prompt.yes?("Configure MCP?")` — for MCP and completions
+
+Options for non-interactive/partial use:
+- `--driver DRIVER` — skip driver prompt
+- `--force` — overwrite existing config
+- `--skip-mcp` — skip MCP configuration step
+- `--skip-completions` — skip shell completion offer
+
+Register in `cli.rb`:
+```ruby
+require_relative "cli/setup"
+register CLI::Setup, "setup", "setup", "Interactive first-time setup"
+```
+
+### Step 6: Tests
+
+**`test/setup_test.rb`** — tests for the `Setup` class:
+- `generate_config` with various combinations produces valid YAML (after ERB substitution)
+- `detect_drivers` returns all registered drivers with installed status
+- `available_*` methods return only integrations with `setup_label`
+- Generated config preserves ERB `env()` helpers literally (not evaluated)
+- Sections are omitted when no items selected for that category
+- Settings section is always present (commented out)
+
+**`test/setup_config_test.rb`** — validates all integration `setup_config` implementations:
+- Every integration with `setup_label` also has `setup_config`
+- Each `setup_config` returns a non-empty string
+- Each `setup_config` is valid YAML after substituting dummy values for ERB `env()` calls
+- Required config keys from `required_config` appear in the setup_config (either uncommented or as comments)
+
+### Step 7: Documentation updates
+
+- **`CLAUDE.md`** — add `Setup` to key classes, add `setup_config`/`setup_label` to Poller/Notifier/RepositorySource class docs, update CLI commands section, update directory structure
+- **`README.md`** — update quickstart to lead with `superkick setup`
+- **`docs/tutorials/getting-started.md`** — replace manual config creation steps with `superkick setup` as step 1
+- **Skills** (`superkick-new-monitor`, `superkick-new-spawner`, `superkick-new-notifier`) — mention `setup_config` and `setup_label` as optional methods
+- **`lib/superkick/cli/completion.rb`** — add `setup` to top-level completions
+
+## File Changes Summary
+
+**New files:**
+- `lib/superkick/setup.rb`
+- `lib/superkick/cli/setup.rb`
+- `test/setup_test.rb`
+- `test/setup_config_test.rb`
+
+**Modified — base classes (add `setup_config` + `setup_label` defaults):**
+- `lib/superkick/poller.rb`
+- `lib/superkick/notifier.rb`
+- `lib/superkick/repository_source.rb`
+
+**Modified — integration `setup_config` + `setup_label` additions:**
+- `lib/superkick/integrations/github/monitor.rb`
+- `lib/superkick/integrations/circleci/monitor.rb`
+- `lib/superkick/integrations/shortcut/monitor.rb`
+- `lib/superkick/integrations/shell/monitor.rb`
+- `lib/superkick/integrations/datadog/alert_monitor.rb`
+- `lib/superkick/integrations/github/issue_spawner.rb`
+- `lib/superkick/integrations/github/check_failed_spawner.rb`
+- `lib/superkick/integrations/shortcut/spawner.rb`
+- `lib/superkick/integrations/slack/spawner.rb`
+- `lib/superkick/integrations/bugsnag/spawner.rb`
+- `lib/superkick/integrations/datadog/spawner.rb`
+- `lib/superkick/integrations/datadog/alert_spawner.rb`
+- `lib/superkick/integrations/honeybadger/spawner.rb`
+- `lib/superkick/notifiers/terminal_bell.rb`
+- `lib/superkick/notifiers/command.rb`
+- `lib/superkick/integrations/slack/notifier.rb`
+- `lib/superkick/integrations/datadog/notifier.rb`
+- `lib/superkick/integrations/honeybadger/notifier.rb`
+- `lib/superkick/local/repository_source.rb`
+- `lib/superkick/integrations/git/repository_source.rb`
+- `lib/superkick/integrations/github/repository_source.rb`
+
+**Modified — wiring:**
+- `superkick.gemspec` — add `tty-prompt` dependency
+- `lib/superkick/cli.rb` — register Setup subcommand
+- `lib/superkick.rb` — require `setup`
+- `lib/superkick/cli/completion.rb` — add `setup` to completions
+
+**Documentation:**
+- `CLAUDE.md`
+- `README.md`
+- `docs/tutorials/getting-started.md`
+- `skills/superkick-new-monitor/SKILL.md`
+- `skills/superkick-new-spawner/SKILL.md`
+- `skills/superkick-new-notifier/SKILL.md`