# 🚀 Gibwork DevOps & Autonomous Agent Suite (`gibwork-devops-kit`)

> **Gibwork Developer Hackathon Submission**  
> *Track: Non-Web-App Developer Workflows, Tooling, and Automations*  
> **Toolsets Used:** Gibwork Core SDK, Terminal CLI (`gibctl`), and Model Context Protocol (MCP) Server.

---

## 📖 Executive Summary & Value Proposition

Web3 bounty platforms often suffer from a severe **context-switching bottleneck**:
1. **Maintainers** must leave their code editor, open a browser, connect a browser wallet, manually type descriptions on `app.gib.work`, and manually reconcile GitHub issues with bounty payments.
2. **Developers & Bounty Hunters** have to refresh web dashboards, parse tasks manually, manually clone repositories, and create branches.
3. **AI Coding Agents** (such as Claude Desktop, Cursor, and Antigravity) cannot seamlessly discover, assess, and solve Gibwork bounties without native protocol tools.

**`gibwork-devops-kit` is a 100% non-web-app developer automation ecosystem** that brings Gibwork directly to:
- **Your Terminal:** Via `gibctl`, a high-performance, colorized CLI for discovering, creating, triaging, and solving bounties.
- **Your Codebase & CI/CD:** Via GitOps automation (GitHub Actions) and repository triage that detects technical debt (`TODO`, `FIXME`, `OPTIMIZE`) and estimates bounty budgets.
- **Your AI Coding Assistant:** Via a standardized **Model Context Protocol (MCP)** server providing 6 autonomous tools for search, task ingestion, solution scaffolding, and deliverable verification.
- **Your Scripts & Services:** Via a robust, typed **TypeScript SDK** supporting both live Gibwork APIs (`https://api2.gib.work`) and an offline sandbox simulation mode.

---

## 🏗️ Architecture & Workflow

```mermaid
flowchart TD
    subgraph Maintainer_Workflow["1. Maintainer Workflow"]
        Codebase["Source Code / Repository"] -->|gibctl triage| TriageReport["Technical Debt Triage & Bounty Sizing"]
        TriageReport -->|gibctl create| Provision["On-Chain Escrow Creation"]
        Issue["GitHub Issue Tagged 'bounty'"] -->|GitHub Action| AutoBounty["CI/CD Automated Bounty Provisioning"]
    end

    subgraph Core_Engine["2. Gibwork DevOps Kit Core"]
        SDK["Gibwork Core SDK (@gibwork/sdk)"]
        CLI["Terminal CLI (gibctl)"]
        MCP["Gibwork MCP Server (JSON-RPC)"]
        Sandbox["Resilient Dual-Mode Engine (Live API + Sandbox)"]
    end

    subgraph Developer_Agent_Workflow["3. Contributor & AI Agent Workflow"]
        MCP -->|gibwork_search_bounties| Claude["Claude Desktop / Cursor / Antigravity"]
        Claude -->|gibwork_scaffold_solution| Solution["Code & Test Implementation"]
        CLI -->|gibctl solve| Workspace["Local Git Branch & Bounty Brief"]
        CLI -->|gibctl verify| Receipt["Cryptographic Completion Receipt"]
    end

    Maintainer_Workflow --> Core_Engine
    Core_Engine --> Developer_Agent_Workflow
```

---

## 🧰 The 4 Unified Pillars

| Pillar | Component | Target Audience | Key Capabilities |
|--------|-----------|-----------------|------------------|
| **1. SDK** | `GibworkClient` (`src/sdk/`) | Backend & script developers | Typed API client for tasks, exploration, Solana Web3 transaction creation, and offline sandbox mocking. |
| **2. CLI** | `gibctl` (`src/cli/`) | Terminal-first developers | `explore`, `view`, `create`, `triage`, `solve`, `verify`, and `report` commands with rich formatting. |
| **3. MCP** | `gibwork-mcp-server` (`src/mcp/`) | AI assistants (Claude, Cursor) | 6 tools: search, get, create, triage codebase, scaffold solution, and validate deliverables. |
| **4. GitOps** | `.github/workflows/` | Open-source maintainers | Automated bounty minting on issue labels and cryptographic deliverable verification on PR merges. |

---

## ⚡ Quick Start & Installation

### Prerequisites
- Node.js (v18 or higher; tested on v22 & v24)
- npm (v9 or higher)
- Solana wallet (optional; mock sandbox mode allows full testing without funds)

### Installation
```bash
# 1. Clone repository
git clone https://github.com/ranadheer-designs/gibwork-devops-kit.git
cd gibwork-devops-kit

# 2. Install dependencies
npm install

# 3. Build TypeScript files
npm run build

# 4. Link CLI globally (optional)
npm link
```

### Environment Configuration
Copy `.env.example` to `.env`:
```bash
cp .env.example .env
```

| Variable | Default | Description |
|----------|---------|-------------|
| `GIBWORK_API_URL` | `https://api2.gib.work` | Base URL for Gibwork API |
| `GIBWORK_MOCK_MODE` | `false` | When `true`, operates in local sandbox mode without requiring network access |
| `SOLANA_RPC_URL` | `https://api.mainnet-beta.solana.com` | Solana RPC endpoint |
| `SOLANA_PRIVATE_KEY` | *(optional)* | Base58 private key for signing live escrow transactions |
| `DEFAULT_TOKEN_MINT` | `EPjFWdd5Aufq...` | Default reward token (USDC on Solana) |

---

## 💻 Terminal CLI (`gibctl`) Command Reference

### 1. Explore Active Bounties
Browse and search bounties from the command line with colored tables:
```bash
# Browse latest bounties
gibctl explore

# Filter by tags and minimum reward
gibctl explore --tag "solana,rust" --min 300 --limit 5

# Output raw JSON for scripting
gibctl explore --json
```

**Sample Output:**
```
🔍 Found 5 Gibwork bounties

┌──────────────────────┬──────────────┬────────────────┬────────────────────────────────────┬──────────────────────────┬────────────┐
│ Task ID              │ Reward       │ Difficulty     │ Title                              │ Tags                     │ Status     │
├──────────────────────┼──────────────┼────────────────┼────────────────────────────────────┼──────────────────────────┼────────────┤
│ gw-task-sec-04       │ $1200 USDC   │  EXPERT        │ Audit & Fuzz Test Compressed NFTs  │ #security #solana        │ ● OPEN     │
│ gw-task-solana-01    │ $450 USDC    │  ADVANCED      │ Implement SPL Token-2022 Transfer  │ #solana #rust #anchor    │ ● OPEN     │
│ gw-task-cli-03       │ $250 USDC    │  INTERMEDIATE  │ Develop Fast Terminal TUI          │ #cli #tui #solana        │ ● OPEN     │
└──────────────────────┴──────────────┴────────────────┴────────────────────────────────────┴──────────────────────────┴────────────┘
```

### 2. View Task Details & Requirements
```bash
gibctl view gw-task-solana-01
```

### 3. Triage Codebase for Technical Debt
Scan any local directory for `TODO`, `FIXME`, `HACK`, and `OPTIMIZE` markers. `gibctl` automatically estimates bounty size in USDC and recommends tags:
```bash
# Scan a codebase
gibctl triage --dir ./examples/sample-codebase

# Export triage report to JSON
gibctl triage --dir ./examples/sample-codebase --export deliverables/triage_manifest.json
```

**Sample Output:**
```
📊 Codebase Triage Summary:
   Scanned Files:    1
   Debt Markers:     4
   Suggested Budget: $375 USDC

┌────────────┬────────────────────────────┬──────────────┬────────────────┬────────────────────────────────────────┐
│ Type       │ Location                   │ Est. Bounty  │ Difficulty     │ Description                            │
├────────────┼────────────────────────────┼──────────────┼────────────────┼────────────────────────────────────────┤
│ TODO       │ orderEngine.ts:9           │ $75 USDC     │  BEGINNER      │ Implement decimal rounding precision   │
│ FIXME      │ orderEngine.ts:14          │ $100 USDC    │  INTERMEDIATE  │ Memory leak occurs when order queue    │
│ OPTIMIZE   │ orderEngine.ts:21          │ $150 USDC    │  ADVANCED      │ Replace linear search with binary tree │
│ TODO       │ orderEngine.ts:29          │ $50 USDC     │  BEGINNER      │ Add HMAC signature verification        │
└────────────┴────────────────────────────┴──────────────┴────────────────┴────────────────────────────────────────┘
```

### 4. Create & Fund a Bounty
Create a Gibwork bounty directly from the command line without opening a browser:
```bash
gibctl create \
  --title "Implement Anchor Event Indexer" \
  --content "Create event listener service for Solana Anchor program" \
  --requirements "1. WebSocket subscription\n2. Retry logic\n3. 100% tests" \
  --tags "solana,typescript,indexer" \
  --amount 300
```

### 5. Solve & Scaffold Bounty Workspace
Generate a dedicated git branch and `bounty-brief.md` context file for you or your AI agent:
```bash
gibctl solve gw-task-solana-01
```

### 6. Verify Deliverable & Mint Proof Receipt
Runs test suites and creates a cryptographic proof hash linking task ID, commit SHA, and contributor address:
```bash
gibctl verify gw-task-solana-01 \
  --contributor "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU" \
  --commit "9e7b23f8102a4b89c7d6e5f4a3b2c1d0ef123456" \
  --export deliverables/submission_receipt.json
```

### 7. Export Bounty Audit Report
```bash
gibctl report --export deliverables/bounty_audit_report.md
```

---

## 🤖 Model Context Protocol (MCP) Integration

The included MCP server allows AI coding agents like **Claude Desktop**, **Cursor**, **Windsurf**, and **Antigravity** to directly operate Gibwork bounties.

### Claude Desktop Configuration
Add the following to your Claude Desktop config (`claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "gibwork": {
      "command": "node",
      "args": ["<PATH_TO_GIBWORK_DEVOPS_KIT>/dist/mcp/server.js"],
      "env": {
        "GIBWORK_MOCK_MODE": "true"
      }
    }
  }
}
```

### MCP Tools Provided

1. `gibwork_search_bounties`: Search active bounties by query, tags, and minimum reward.
2. `gibwork_get_bounty`: Retrieve full requirements, poster info, and token metadata.
3. `gibwork_create_bounty`: Programmatically provision bounties on Solana escrow.
4. `gibwork_triage_codebase`: Analyze local codebases to estimate bounty opportunities.
5. `gibwork_scaffold_solution`: Generate solution architecture, branch names, and PR drafts.
6. `gibwork_validate_deliverable`: Generate cryptographic completion proof receipts for PR submission.

---

## 🧪 Automated Testing

The suite includes 19 automated unit and integration tests using [Vitest](https://vitest.dev):
```bash
npm test
```

Test coverage includes:
- **SDK Tests (`tests/sdk.test.ts`):** Exploration filters, pagination, task fetching, sandbox creation, triage engine, and cryptographic verification.
- **MCP Tests (`tests/mcp.test.ts`):** Tool registration, parameter validation via Zod, and tool call executions.
- **CLI Tests (`tests/cli.test.ts`):** `gibctl` help, `explore --json`, `view --json`, `triage --json`, and `verify --json`.

---

## 📦 Hackathon Submission Deliverables

As requested by the Gibwork Hackathon requirements:

1. **Source Code & Project:** Full TypeScript repository with strict typing and modular architecture.
2. **Setup Instructions:** Detailed steps to run, build, and configure the project.
3. **Exported Deliverables:**
   - [`deliverables/bounty_audit_report.md`](deliverables/bounty_audit_report.md): Exported Markdown audit report.
   - [`deliverables/submission_receipt.json`](deliverables/submission_receipt.json): Cryptographic completion receipt.
   - [`deliverables/triage_manifest.json`](deliverables/triage_manifest.json): Exported codebase debt triage manifest.
   - [`deliverables/terminal_demo_transcript.txt`](deliverables/terminal_demo_transcript.txt): Verifiable terminal execution logs.

---

## 📜 License

MIT License. Built for the **Gibwork Developer Hackathon**.