superkick 0.1.0

data/CONTRIBUTING.md

@@ -0,0 +1,104 @@
+# Contributing to Superkick
+
+Thank you for your interest in contributing to Superkick.
+
+## Getting started
+
+Clone the repo and install dependencies:
+
+```bash
+git clone https://github.com/your-org/superkick.git
+cd superkick
+bundle install
+```
+
+If you are working in the Claude Code sandbox, see the bootstrap steps in
+[CLAUDE.md](CLAUDE.md#claude-code-sandbox-bootstrap) first.
+
+## Running tests
+
+```bash
+# Full test suite + lint (the default)
+bundle exec rake
+
+# Tests only
+bundle exec rake test
+
+# Single test file
+bundle exec rake test TEST=test/injector_test.rb
+
+# Specific test by name
+bundle exec rake test TEST=test/injector_test.rb TESTOPTS="-n test_returns_skipped_when_gate_refuses"
+
+# Lint only
+bundle exec rake standard
+
+# Auto-fix lint violations
+bundle exec rake standard:fix
+```
+
+All tests must pass and the linter must report no violations before a pull
+request can be merged.
+
+## Making changes
+
+- Keep pull requests focused on a single concern.
+- Follow the existing code style (StandardRB, zero config).
+- Add or update tests for any behaviour you change.
+- All lib files use `# frozen_string_literal: true` — keep it that way.
+
+### Adding a new driver
+
+See [skills/superkick-new-driver/SKILL.md](skills/superkick-new-driver/SKILL.md) for
+the step-by-step guide.
+
+### Adding a new monitor
+
+See [skills/superkick-new-monitor/SKILL.md](skills/superkick-new-monitor/SKILL.md)
+for the step-by-step guide.
+
+### Adding a new spawner
+
+See [skills/superkick-new-spawner/SKILL.md](skills/superkick-new-spawner/SKILL.md)
+for the step-by-step guide. Spawners support workflow hooks (`on_complete:` /
+`on_fail:`) for multi-stage pipelines — the skill covers designing spawners
+that work well in chains.
+
+### Adding a new goal
+
+See [skills/superkick-new-goal/SKILL.md](skills/superkick-new-goal/SKILL.md) for the
+step-by-step guide.
+
+### Adding a new version control adapter
+
+See [skills/superkick-new-version-control/SKILL.md](skills/superkick-new-version-control/SKILL.md)
+for the step-by-step guide.
+
+### Adding a new repository source
+
+See [skills/superkick-new-repository-source/SKILL.md](skills/superkick-new-repository-source/SKILL.md)
+for the step-by-step guide.
+
+### Adding a new notifier
+
+See [skills/superkick-new-notifier/SKILL.md](skills/superkick-new-notifier/SKILL.md)
+for the step-by-step guide.
+
+### Adding a new agent runtime
+
+See [skills/superkick-new-runtime/SKILL.md](skills/superkick-new-runtime/SKILL.md)
+for the step-by-step guide.
+
+## Submitting a pull request
+
+1. Fork the repository and create a branch from `main`.
+2. Make your changes, ensuring tests pass and the linter is clean.
+3. Open a pull request with a clear description of what changes you made and
+   why.
+
+## License
+
+By submitting a contribution, you agree to the terms of the
+[Contributor License Agreement](CLA.md). In short: you retain ownership of your
+work, and you grant the Maintainer the right to distribute it under both the
+[Business Source License 1.1](LICENSE) and a [commercial license](LICENSE-COMMERCIAL.md).

data/LICENSE

@@ -0,0 +1,108 @@
+Business Source License 1.1
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+-----------------------------------------------------------------------------
+
+Parameters
+
+Licensor:             Superkick Systems, Inc.
+
+Licensed Work:        Superkick
+                      The Licensed Work is (c) 2026 Superkick Systems, Inc.
+
+Additional Use Grant: You may make production use of the Licensed Work,
+                      provided your use does not include offering the Licensed
+                      Work to third parties on a hosted, managed, or embedded
+                      basis in a manner that competes with the Licensor's paid
+                      or commercial versions of the Licensed Work. For purposes
+                      of this license, "compete" means offering a product or
+                      service whose primary value derives substantially from
+                      the functionality of the Licensed Work.
+
+Change Date:          Four years from the date the Licensed Work is published.
+
+Change License:       Apache License, Version 2.0
+
+-----------------------------------------------------------------------------
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+-----------------------------------------------------------------------------
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License can
+   be included in a program with software provided under GPL Version 2.0 or a
+   later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.
+
+-----------------------------------------------------------------------------
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.
+
+For more information on the use of the Business Source License, please visit:
+https://mariadb.com/bsl11/

data/LICENSE-COMMERCIAL.md

@@ -0,0 +1,39 @@
+# Superkick Commercial License
+
+The Superkick source code is made available under the Business Source License 1.1
+(see [LICENSE](LICENSE)). The BSL permits non-production use and production use
+that does not compete with the Licensor's offerings.
+
+## When you need a commercial license
+
+You need a separate commercial license if your use of Superkick falls outside the
+BSL's Additional Use Grant — for example, if you are offering Superkick (or a
+product built substantially on Superkick) to third parties as a hosted, managed, or
+SaaS product.
+
+## What the commercial license provides
+
+A commercial license grants you:
+
+- **Production use** without the BSL's non-compete restriction
+- **Redistribution rights** for embedding Superkick in your own product
+- **Priority support** and direct access to the maintainer
+- **Custom terms** tailored to your use case
+
+## Pricing
+
+Commercial licenses are priced on a case-by-case basis depending on the nature
+and scale of your use. Founder-friendly terms are available for startups and
+small teams.
+
+## Contact
+
+To discuss commercial licensing, please reach out:
+
+- **Email:** licensing@superkick.ai
+- **GitHub:** Open a [licensing inquiry](https://github.com/admtnnr/superkick/issues/new?title=Commercial+License+Inquiry)
+
+---
+
+*This document is informational and does not constitute a license. The binding
+license terms are in [LICENSE](LICENSE).*

data/PLAN.md

@@ -0,0 +1,161 @@
+# Docker Runtime Implementation Plan
+
+## Overview
+
+Add `Agent::Runtime::Docker` — a Docker container runtime that provisions spawned agents in Docker containers via the Docker Engine API. Uses Faraday for HTTP (Unix socket and TCP+TLS), following established codebase patterns.
+
+## Existing plumbing
+
+`Configuration#build_agent_runtime` (line 107) already has a `when :docker` branch that passes the `docker:` config hash to the constructor. We just need to build the class it instantiates.
+
+## Implementation steps
+
+### Step 1: Docker Engine API client (`lib/superkick/docker/client.rb`)
+
+A thin Faraday-based wrapper around the Docker Engine API endpoints we need. Accepts `connection:` for test injection.
+
+**Constructor:** `initialize(host:, tls: nil, connection: nil)`
+- `host` — `unix:///var/run/docker.sock` or `tcp://host:port`
+- `tls` — optional Hash `{ ca:, cert:, key: }` for TCP+TLS
+- `connection` — injected Faraday connection (tests)
+
+**Methods:**
+- `create_container(name:, config:)` → Hash (container ID, warnings)
+- `start_container(id:)` → nil
+- `stop_container(id:, timeout: 30)` → nil
+- `remove_container(id:, force: false)` → nil
+- `inspect_container(id:)` → Hash (full container state)
+- `pull_image(image:, auth: nil)` → nil (blocks until complete)
+- `image_exists?(image:)` → Boolean
+- `ping` → Boolean (health check)
+
+**Faraday Unix socket:** Faraday supports Unix sockets via the URL scheme `http+unix:///path/to/socket`. The base URL becomes `http+unix:///var/run/docker.sock/` and paths are appended normally (`/v1.47/containers/create`).
+
+**API version:** Pin to `v1.47` (Docker 27.x). All endpoints are prefixed with this version.
+
+**Error handling:** Define `Docker::Client::Error` (base), `Docker::Client::NotFound` (404), `Docker::Client::Conflict` (409). Map HTTP status codes to these.
+
+### Step 2: Docker runtime (`lib/superkick/agent/runtimes/docker.rb`)
+
+**Constructor:** `initialize(image:, host: nil, tls: nil, registry: nil, pull_policy: :missing, memory: nil, cpu: nil, network: nil, stop_timeout: 30, auto_remove: true, env: nil, volumes: nil, labels: nil, connection: nil)`
+
+All config keys from the YAML `docker:` section map directly to constructor kwargs. The `connection:` param is for test injection into the underlying `Docker::Client`.
+
+**Handle:** `Data.define(:container_id, :container_name)`
+
+**`provision(agent_id:, config:)`:**
+1. Pull image (respecting `pull_policy`)
+2. Build container config hash:
+   - `Image` — from constructor
+   - `Cmd` — from `config[:command]`
+   - `Env` — merge runtime-level `env` with `config[:env]` (config wins)
+   - `WorkingDir` — from `config[:working_dir]`
+   - `HostConfig.Memory` — parse memory string (e.g. `"4G"` → bytes)
+   - `HostConfig.NanoCpus` — parse cpu (e.g. `2` → 2_000_000_000)
+   - `HostConfig.Binds` — from `volumes`
+   - `HostConfig.NetworkMode` — from `network`
+   - `Labels` — merge runtime labels with `{ "superkick.agent_id" => agent_id }`
+   - `StopTimeout` — from `stop_timeout`
+3. Create container with name `superkick-#{agent_id}`
+4. Start container
+5. Return `Handle.new(container_id:, container_name:)`
+
+**`terminate(handle:)`:**
+1. Stop container (with `stop_timeout`)
+2. Remove container if `auto_remove` is true
+3. Rescue `Docker::Client::NotFound` silently (already gone)
+
+**`alive?(handle:)`:**
+1. Inspect container
+2. Return `state["Running"]`
+3. Rescue `Docker::Client::NotFound` → false
+
+**`metadata(handle:)`:**
+```ruby
+{ container_id: handle.container_id, container_name: handle.container_name }
+```
+
+### Step 3: Memory size parser (private helper)
+
+Parse Docker memory strings: `"4G"` → `4_294_967_296`, `"512M"` → `536_870_912`, `"1024K"` → `1_048_576`. If already an Integer, pass through. Lives as a private method on the Docker runtime class.
+
+### Step 4: Update `Configuration#build_agent_runtime`
+
+The existing `when :docker` branch needs updating. Current code:
+
+```ruby
+when :docker
+  docker_config = @runtime[:docker] || {}
+  klass.new(**docker_config.except(:socket).merge(
+    socket: docker_config[:socket] || "/var/run/docker.sock"
+  ))
+```
+
+Update to pass `host:` instead of `socket:` (since the config key is `host:`), and pass the full docker config hash through:
+
+```ruby
+when :docker
+  docker_config = @runtime[:docker] || {}
+  klass.new(**docker_config)
+```
+
+The Docker runtime constructor handles all defaults internally.
+
+### Step 5: Register and require
+
+1. Self-register at bottom of `docker.rb`: `Superkick::Agent::Runtime.register(Superkick::Agent::Runtime::Docker)`
+2. Add `require_relative "runtimes/docker"` to `lib/superkick/agent/runtimes.rb`
+
+### Step 6: Tests
+
+**`test/docker/client_test.rb`** — test the Faraday-based Docker client:
+- `ping` — success and failure
+- `create_container` — sends correct JSON, returns container ID
+- `start_container` / `stop_container` / `remove_container` — correct HTTP methods and paths
+- `inspect_container` — parses response
+- `pull_image` — correct endpoint, sends auth header when registry config provided
+- `image_exists?` — true on 200, false on 404
+- Error mapping (404 → NotFound, 409 → Conflict, 500 → Error)
+
+All tests use `Faraday::Adapter::Test::Stubs` with `connection:` injection.
+
+**`test/agent/runtimes/docker_test.rb`** — test the runtime:
+- `type` returns `:docker`
+- `provision` — pulls image (when policy requires it), creates container with correct config, starts it, returns Handle
+- `provision` — merges env correctly (config env overrides runtime env)
+- `provision` — parses memory/cpu into Docker API format
+- `provision` — skips pull when `pull_policy: :never`
+- `terminate` — stops and removes container
+- `terminate` — handles already-removed container
+- `alive?` — returns true/false based on container state
+- `alive?` — returns false when container not found
+- `metadata` — returns container_id and container_name
+- Memory parser — various units and passthrough
+
+Tests stub the `Docker::Client` methods rather than HTTP, keeping them focused on runtime logic.
+
+### Step 7: Documentation
+
+1. **CLAUDE.md** — update directory structure (add `docker/` dir), add Docker runtime to Key Classes section, update `build_agent_runtime` description, update runtime config example
+2. **README.md** — add Docker runtime section under configuration/deployment
+3. **`docs/tutorials/first-spawner-pipeline.md`** — mention Docker runtime as an option
+4. **`docs/explanation/spawner-workflows.md`** — note runtime choice affects agent isolation
+
+## File list
+
+New files:
+- `lib/superkick/docker/client.rb`
+- `test/docker/client_test.rb`
+- `lib/superkick/agent/runtimes/docker.rb`
+- `test/agent/runtimes/docker_test.rb`
+
+Modified files:
+- `lib/superkick/agent/runtimes.rb` (add require)
+- `lib/superkick/configuration.rb` (update `build_agent_runtime`)
+- `lib/superkick.rb` (add require for `docker/client`)
+- `CLAUDE.md` (docs)
+- `README.md` (docs)
+
+## Open questions
+
+None — config surface is agreed, patterns are clear from existing code.