Skip to content

v1.0.0 - Connector: Foundation for Agent Operations

Choose a tag to compare

View all tags
@jordanpartridge jordanpartridge released this 11 Dec 04:48
· 17 commits to master since this release
v1.0.0
b315dce

Connector v1.0.0 - Foundation for Deterministic Agent Operations

Overview

The Connector package is the foundational HTTP transport layer for the Conduit ecosystem. It provides bare-metal GitHub API operations that agents need to work deterministically with repositories, issues, and pull requests.

Why Connector Exists

Agents need predictable, testable GitHub operations - not fancy wrappers or opinionated abstractions. Connector is deliberately minimal:

  • Pure transport: HTTP + authentication, nothing more
  • No business logic: Domain operations live in higher-level packages (issues, prs, repos)
  • Deterministic: Same input → same output, always
  • Testable: 24 tests, 54 assertions, all passing

Architecture Position

```
┌─────────────────────────────────────────────┐
│ Agent Swarms (Docker) │
│ architect | implementer | tester | reviewer│
└─────────────────┬───────────────────────────┘
│
┌─────────────────▼───────────────────────────┐
│ Domain Packages │
│ conduit-ui/issues │
│ conduit-ui/prs │
│ conduit-ui/repos │
└─────────────────┬───────────────────────────┘
│
┌─────────────────▼───────────────────────────┐
│ conduit-ui/connector │
│ HTTP transport + GitHub auth │
│ Exception mapping + rate limiting │
└─────────────────┬───────────────────────────┘
│
▼
GitHub API v3
```

Changes from github-connector

This release completes the rename from `github-connector` to `connector`:

Breaking Changes

  • Package: `conduit-ui/github-connector` → `conduit-ui/connector`
  • Class: `GithubConnector` → `Connector`
  • Interface: `GithubConnectorInterface` → `ConnectorInterface`
  • Namespace: `ConduitUI\GithubConnector` → `ConduitUi\GitHubConnector`

Migration

```php
// Before
use ConduitUI\GithubConnector\GithubConnector;
$connector = new GithubConnector($token);

// After
use ConduitUi\GitHubConnector\Connector;
$connector = new Connector($token);
```

Features

  • Saloon v3 Integration: Modern HTTP client with excellent DX
  • GitHub Authentication: Token-based auth with proper headers
  • Exception Hierarchy:
    • `AuthenticationException` (401)
    • `ValidationException` (422)
    • `ResourceNotFoundException` (404)
    • `RateLimitException` (403 with rate limit headers)
    • `ForbiddenException` (403 without rate limit)
    • `ServerException` (5xx)
  • Rate Limit Detection: Automatic detection from response headers
  • PSR-12 Compliant: Clean, consistent code style
  • PHPStan Max Level: Zero static analysis errors

Requirements

  • PHP 8.2, 8.3, or 8.4
  • Saloon ^3.10

Installation

```bash
composer require conduit-ui/connector
```

Usage

```php
use ConduitUi\GitHubConnector\Connector;

$connector = new Connector(env('GITHUB_TOKEN'));

// GET request
$response = $connector->send(
$connector->get('/repos/owner/repo')
);

// POST request
$response = $connector->send(
$connector->post('/repos/owner/repo/issues', [
'title' => 'New issue',
'body' => 'Issue description'
])
);
```

Conduit Strategy

The Vision

Conduit is a developer liberation platform - escape corporate tool tyranny with component-based, AI-orchestrated workflows. The ecosystem consists of:

  1. connector (this package) - HTTP transport foundation
  2. issues/prs/repos - Domain operations built on connector
  3. the-shit/agents - Laravel Zero CLI for agent deployment
  4. the-shit/chat - Human orchestration layer

Agent Architecture (Joe Justice Principles)

  • Swarm methodology: Multiple agents attack problems in parallel
  • Mob programming for AI: Architect designs, implementer builds, tester validates, reviewer approves
  • Humans as orchestrators: Strategic guidance, not line-by-line coding
  • Bad PR > No PR: Ship fast, iterate faster

Musk's Algorithm Applied

  1. Question the requirement: Do we need this abstraction?
  2. Delete: Remove unnecessary complexity (github-zero → gh CLI)
  3. Simplify: Single-word package names, minimal APIs
  4. Accelerate: Parallel agent execution
  5. Automate: Event-driven orchestration

Test Results

```
PASS Tests\Unit\ConnectorTest (7 tests)
PASS Tests\Unit\ConnectorExceptionMappingTest (7 tests)
PASS Tests\Unit\ConnectorRateLimitHeaderTest (5 tests)
PASS Tests\Unit\Exceptions\GitHubExceptionTest (5 tests)

Tests: 24 passed (54 assertions)
Duration: 0.19s
```

What's Next

  • v1.1.0: GraphQL support for complex queries
  • v1.2.0: Webhook signature verification
  • v2.0.0: Multi-provider support (GitLab, Bitbucket)

Contributing

Issues and PRs welcome at conduit-ui/connector

Part of the Conduit ecosystem - Your personal developer API gateway

Assets 2
Loading