GitTinkerer Web UI (Svelte)¶

SvelteKit web interface for GitTinkerer. Submit instructions and repository details to create automated runs, monitor progress in real-time, review results, and manage admin operations.

Quick Links: - API Reference — Complete endpoint specification with request/response schemas - Development Guide — Setup, testing, and debugging instructions - Architecture Overview — System context and data flow diagrams

Setup¶

cd web
npm install
npm run dev

• Dev server binds to 0.0.0.0:5173 (preview: 0.0.0.0:4173)
• Service URL configured via VITE_SERVICE_URL environment variable (default: http://localhost:3000)
• See DEVELOPMENT.md for full local setup instructions

Routes & Features¶

The UI is organized into five main routes, each handling a distinct feature:

graph LR
    A["/ Start Run"] -->|create| B["/runs History"]
    B -->|select| C["/runs/[id] Detail"]
    C -->|status| C
    A -->|admin token| D["/admin Controls"]
    A -->|admin token| E["/analytics Dashboard"]

    style A fill:#4A90E2
    style B fill:#F5A623
    style C fill:#7ED321
    style D fill:#BD10E0
    style E fill:#50E3C2

Route Details¶

/ — Start a Run¶

Create a new automated run with an instruction and repository details.

User Flow: 1. Enter instruction text (what the code should do) 2. Enter GitHub repository URL (e.g., https://github.com/owner/repo) 3. (Optional) specify branch/ref (defaults to default branch) 4. Submit → POST /api/runs with instruction payload 5. Redirect to /runs/:run_id to monitor progress

Components: - Run creation form with input validation - Repository and branch/ref selection - Real-time submission feedback

/runs — Run History¶

List all runs with filtering, sorting, and pagination.

Features: - Display run status (running, completed, failed) - Filter by repo, status, date range - Sort by creation date, status, duration - Pagination with configurable page size - Live status polling (updates every few seconds) - Quick links to run details

API Usage: - GET /api/runs?page=1&limit=20&filter=... — List runs with optional filters

/runs/[id] — Run Detail¶

Monitor a specific run's progress and review results.

Sections: 1. Status Summary — Current state, exit code, run duration 2. Instruction & Repo — What was requested and where 3. Summary Output — Markdown summary from summary_md (rendered live as run progresses) 4. Artifacts — Browse generated files and logs 5. Failure Information — Error stage and message (if run failed)

API Usage: - GET /api/runs/:run_id — Get run details (status, artifacts path, summary) - Polling mechanism: every 2–5 seconds until run completes or user navigates away

/admin — Admin Controls¶

Admin-only interface for repository and run management.

Features: - Pause/Resume Repository: Prevent new runs from starting on specific repos - POST /api/admin/pause-repo / POST /api/admin/unpause-repo - View list of paused repos (GET /api/admin/paused-repos)

• Pause/Resume Run Target: Pause specific (repo, branch) combinations

• POST /api/admin/pause-run-target / POST /api/admin/unpause-run-target

• Retry Failed Runs: Resubmit runs that exited with errors

• Manual retry trigger from run detail page or admin panel

Access Control: - Admin token required in Authorization: Bearer <admin_token> header - Enforced by middleware; invalid tokens return 401 Unauthorized

/analytics — Analytics Dashboard¶

Usage metrics and cost estimation dashboard.

Sections: 1. Token Metrics — Total tokens consumed, breakdown by endpoint/feature 2. Run Statistics — Total runs, success rate, average duration 3. Cost Estimate — Projected costs based on current usage patterns 4. CSV Export — Download metrics as CSV for external analysis

API Usage: - GET /api/analytics — Aggregate metrics (calls to /api aggregateMetrics use case) - Export endpoint returns CSV data

API Integration Patterns¶

Form Submission & Run Creation¶

// POST /api/runs with payload
const response = await fetch('/api/runs', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    instruction: "Add a feature...",
    repo: "https://github.com/owner/repo",
    ref: "main"
  })
});

const { run_id } = await response.json();
// Redirect to /runs/:run_id

Live Polling (Status Updates)¶

// Poll /api/runs/:id until completion
const poll = async () => {
  const response = await fetch(`/api/runs/${runId}`);
  const run = await response.json();

  if (run.status === 'completed' || run.status === 'failed') {
    // Stop polling, render final state
  } else {
    // Continue polling after delay
    setTimeout(poll, 3000);
  }
};

Admin Token Authentication¶

// Include token in Authorization header for admin endpoints
const headers = {
  'Authorization': `Bearer ${adminToken}`,
  'Content-Type': 'application/json'
};

const response = await fetch('/api/admin/pause-repo', {
  method: 'POST',
  headers,
  body: JSON.stringify({ repo: 'owner/repo' })
});

Pagination (Run History)¶

// List with page and limit parameters
const response = await fetch('/api/runs?page=1&limit=20');
const { runs, total, page, limit } = await response.json();