npm package: @saeed42/worktree-worker
Description: Git worktree management service for AI agent trials
Author: Origin
Latest version: 1.7.2

# @saeed42/worktree-worker

Git worktree management service for AI agent trials. Runs as an npm package in CodeSandbox or any
Node.js environment.

## Security

**GitHub tokens are NEVER persisted to disk.** All authenticated operations require the token to be
passed in the request body. This is critical for sandbox environments where credentials should not
be stored.

## Installation

```bash
# Install globally
npm install -g @saeed42/worktree-worker

# Or add to your project
npm install @saeed42/worktree-worker
```

## Quick Start

### Run as CLI

```bash
# Set environment variables
export WORKER_TOKEN=your-secret-token
export PORT=8787

# Run the service
worktree-worker
```

### Run in CodeSandbox

Add to your `package.json`:

```json
{
  "dependencies": {
    "@saeed42/worktree-worker": "^1.0.0"
  },
  "scripts": {
    "worktree-worker": "worktree-worker"
  }
}
```

Or run directly:

```bash
npx @saeed42/worktree-worker
```

### Run Programmatically

```typescript
import { app } from '@saeed42/worktree-worker';

// The app is a Hono instance
// You can extend it or use it as middleware
```

## Architecture

```
/project/
├── sandbox/              # BASE_WORKSPACE_DIR - Main repo clone
└── workspaces/
    └── trials/           # TRIALS_WORKSPACE_DIR - Worktrees
        ├── feature-auth-a1b2c3d4/
        ├── fix-bug-xyz-5e6f7g8h/
        └── ...
```

## API Endpoints

### Health Checks

| Endpoint            | Description        |
| ------------------- | ------------------ |
| `GET /health`       | Basic health check |
| `GET /health/ready` | Readiness check    |
| `GET /health/live`  | Liveness check     |

### Repository Management

| Endpoint                | Description       |
| ----------------------- | ----------------- |
| `POST /v1/repo/init`    | Clone repository  |
| `POST /v1/repo/update`  | Fetch/pull latest |
| `GET /v1/repo/status`   | Get repo status   |
| `GET /v1/repo/branches` | List branches     |

### Worktree Management

| Endpoint                                   | Description           |
| ------------------------------------------ | --------------------- |
| `POST /v1/trials/:trialId/worktree/reset`  | Create/reset worktree |
| `DELETE /v1/trials/:trialId/worktree`      | Delete worktree       |
| `GET /v1/trials/:trialId/worktree/status`  | Get status            |
| `GET /v1/trials/:trialId/worktree/diff`    | Get diff              |
| `POST /v1/trials/:trialId/worktree/commit` | Commit changes        |
| `POST /v1/trials/:trialId/worktree/push`   | Push to remote        |

## Configuration

| Variable               | Default                      | Description                  |
| ---------------------- | ---------------------------- | ---------------------------- |
| `PORT`                 | `8787`                       | HTTP server port             |
| `NODE_ENV`             | `development`                | Environment mode             |
| `WORKER_TOKEN`         | ``                           | Auth token (empty = no auth) |
| `BASE_WORKSPACE_DIR`   | `/project/sandbox`           | Main repo path               |
| `TRIALS_WORKSPACE_DIR` | `/project/workspaces/trials` | Worktrees path               |
| `DEFAULT_BRANCH`       | `main`                       | Default base branch          |
| `GIT_TIMEOUT_MS`       | `60000`                      | Git timeout                  |
| `CLEANUP_AFTER_HOURS`  | `24`                         | Stale worktree cleanup       |

## Usage Examples

### Initialize Repository

```bash
curl -X POST http://localhost:8787/v1/repo/init \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "repoUrl": "https://github.com/owner/repo",
    "branch": "main",
    "githubToken": "ghp_xxx"
  }'
```

### Create Worktree

```bash
curl -X POST http://localhost:8787/v1/trials/abc123/worktree/reset \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "baseBranch": "main",
    "trialBranch": "feature/my-feature",
    "githubToken": "ghp_xxx"
  }'
```

> **Note:** `githubToken` is required for private repositories. The token is used inline and **never
> stored on disk**.

Response:

```json
{
  "success": true,
  "data": {
    "worktreePath": "/project/workspaces/trials/feature-my-feature-abc12345",
    "branch": "feature/my-feature",
    "headSha": "a1b2c3d4e5f6..."
  }
}
```

### Commit Changes

```bash
curl -X POST http://localhost:8787/v1/trials/abc123/worktree/commit \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "feat: implement auth",
    "author": {
      "name": "AI Agent",
      "email": "agent@origin.ai"
    }
  }'
```

### Push Changes

```bash
curl -X POST http://localhost:8787/v1/trials/abc123/worktree/push \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "githubToken": "ghp_xxx",
    "force": false
  }'
```

> **Note:** `githubToken` is **required** for push operations. The token is used inline and **never
> stored on disk**.

## Development

```bash
# Clone the repo
cd worker-service-node

# Install dependencies
npm install

# Run in dev mode (with watch)
npm run dev

# Type check
npm run typecheck

# Build
npm run build

# Run production build
npm start
```

## Publishing

```bash
# Build and publish to npm
npm publish --access public
```

## License

MIT