golem-cc 1.0.2 → 2.1.0

package/bin/install.sh

@@ -1,69 +0,0 @@
-#!/usr/bin/env bash
-#
-# Install golem globally
-#
-
-set -euo pipefail
-
-GOLEM_HOME="${GOLEM_HOME:-$HOME/.golem}"
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-
-echo "Installing golem to $GOLEM_HOME..."
-
-# Create directory structure
-mkdir -p "$GOLEM_HOME"/{commands,agents,prompts}
-
-# Copy commands
-cp -r "$SCRIPT_DIR/commands/golem" "$GOLEM_HOME/commands/"
-echo "✓ Installed Claude commands"
-
-# Copy agents and prompts
-cp "$SCRIPT_DIR/golem/agents/"*.md "$GOLEM_HOME/agents/"
-cp "$SCRIPT_DIR/golem/prompts/"*.md "$GOLEM_HOME/prompts/"
-echo "✓ Installed agents and prompts"
-
-# Build TypeScript
-echo "Building TypeScript..."
-cd "$SCRIPT_DIR"
-pnpm build
-
-# Link binaries
-mkdir -p "$HOME/.local/bin"
-ln -sf "$SCRIPT_DIR/bin/golem" "$HOME/.local/bin/golem"
-ln -sf "$SCRIPT_DIR/dist/cli/index.js" "$HOME/.local/bin/golem-api"
-chmod +x "$SCRIPT_DIR/dist/cli/index.js"
-echo "✓ Linked binaries to ~/.local/bin"
-
-# Create env template if not exists
-if [[ ! -f "$GOLEM_HOME/.env" ]]; then
-  cat > "$GOLEM_HOME/.env" << 'EOF'
-# Freshworks/Freshservice
-FRESH_DOMAIN=yourcompany.freshservice.com
-FRESH_API_KEY=your_api_key_here
-
-# Gitea (on-prem)
-GITEA_URL=https://dev.pearlriverresort.com
-GITEA_TOKEN=your_token_here
-GITEA_ORG=CRDE
-
-# Default repo for issues (can be overridden per-project)
-GITEA_REPO=
-EOF
-  echo "✓ Created $GOLEM_HOME/.env template"
-  echo ""
-  echo "⚠️  Edit $GOLEM_HOME/.env with your API credentials"
-fi
-
-# Setup Claude integration
-mkdir -p "$HOME/.claude/commands"
-ln -sf "$GOLEM_HOME/commands/golem" "$HOME/.claude/commands/golem" 2>/dev/null || true
-echo "✓ Linked Claude commands"
-
-echo ""
-echo "Installation complete!"
-echo ""
-echo "Make sure ~/.local/bin is in your PATH:"
-echo '  export PATH="$HOME/.local/bin:$PATH"'
-echo ""
-echo "Then configure your credentials:"
-echo "  $GOLEM_HOME/.env"

package/docs/FRESHSERVICE_SETUP.md

@@ -1,338 +0,0 @@
-# Freshservice API Setup Guide
-
-This document details all the configuration changes required in Freshservice to enable API access for the Golem CLI integration.
-
----
-
-## Prerequisites
-
-- Freshservice account with admin access
-- Access to Admin settings
-
----
-
-## 1. Agent Role Configuration
-
-**Problem:** The "Account Admin" role only provides administrative privileges (managing settings, users, etc.) but does NOT include permissions to access ticket data via API. API calls to `/api/v2/tickets` return `403 Forbidden`.
-
-**Solution:** Your agent account needs an additional "Agent" role that includes ticket permissions.
-
-### Steps:
-
-1. Go to **Admin** → **Agents**
-2. Find your agent account (or the account that will use the API)
-3. Click to edit the agent
-4. Under **Groups and Roles** → **Roles**, add one of these roles:
-   - **IT Agent** (basic ticket access)
-   - **IT Supervisor** (ticket access + reporting)
-   - **IT Manager** (broader permissions)
-   - **IT Operations** (if available)
-
-5. Save the changes
-
-### Required Privileges
-
-The agent role must include these privileges for full API functionality:
-- `manage_tickets` - Create, update, view tickets
-- `view_time_entries` - View time tracking
-- `edit_ticket_properties` - Modify ticket fields
-- `reply_ticket` - Add replies/notes
-
-### Verification
-
-After adding the role, verify via API:
-```bash
-curl -u "YOUR_API_KEY:X" "https://YOUR_DOMAIN.freshservice.com/api/v2/agents/me"
-```
-
-Check the `roles` array in the response - you should see multiple role IDs.
-
----
-
-## 2. API Key Generation
-
-**Location:** Profile Settings → API Key (right side of page)
-
-### Steps:
-
-1. Click your **profile icon** (top right)
-2. Go to **Profile Settings**
-3. Look for **Your API Key** on the right side
-4. Copy the API key
-
-### Alternative Path:
-- **Admin** → **Agents** → Click your name → **API Key** section
-
-### Notes:
-- The API key is tied to your user account and its permissions
-- If you add new roles, you may need to regenerate the API key
-- API key uses Basic Auth: `API_KEY:X` (the password is literally the letter X)
-
----
-
-## 3. Create Custom Ticket Source
-
-**Problem:** When creating tickets via API, they default to "via Phone" as the source, which is misleading.
-
-**Solution:** Create a custom ticket source for API-created tickets.
-
-### Via API:
-
-```bash
-curl -X POST -u "YOUR_API_KEY:X" \
-  -H "Content-Type: application/json" \
-  -d '{"name":"ACE (API)"}' \
-  "https://YOUR_DOMAIN.freshservice.com/api/v2/ticket_fields/sources"
-```
-
-Response:
-```json
-{
-  "source": {
-    "id": 38000360046,
-    "choice_id": 1002,
-    "value": "ACE (API)",
-    "position": 19,
-    "visible": true,
-    "default": false
-  }
-}
-```
-
-**Important:** Save the `choice_id` value (e.g., `1002`) - this is what you pass as the `source` field when creating tickets.
-
-### Via Admin UI:
-
-1. Go to **Admin** → **Ticket Fields** (under Service Desk Settings)
-2. Find the **Source** field
-3. Click to edit/expand it
-4. Add a new choice: `ACE (API)`
-5. Save
-
-### Note on Deleting Sources:
-- Default sources (Email, Phone, Portal, etc.) cannot be deleted
-- Custom sources can only be deleted via the Admin UI (no DELETE API endpoint)
-- To delete: **Admin** → **Ticket Fields** → **Source** → hover over custom source → trash icon
-
----
-
-## 4. Required Fields for Ticket Creation
-
-**Problem:** Freshservice instances may have required fields configured that cause `400 Validation failed` errors.
-
-### Our Instance Requires:
-
-| Field | Type | Example |
-|-------|------|---------|
-| `subject` | string | "Ticket title" |
-| `description` | string | "Ticket description" |
-| `email` | string | "requester@domain.com" |
-| `group_id` | integer | `38000120203` |
-| `category` | string | "Applications" |
-| `source` | integer | `1002` (ACE API) |
-
-### Finding Your Group IDs:
-
-```bash
-curl -u "YOUR_API_KEY:X" "https://YOUR_DOMAIN.freshservice.com/api/v2/groups"
-```
-
-### Finding Valid Categories:
-
-```bash
-curl -u "YOUR_API_KEY:X" "https://YOUR_DOMAIN.freshservice.com/api/v2/ticket_form_fields" | \
-  python3 -c "import sys,json; [print(f['choices']) for f in json.load(sys.stdin)['ticket_fields'] if f['name']=='category']"
-```
-
-Our valid categories: `Hardware`, `Applications`, `Infrastructure`, `Security`
-
-### Finding Source IDs:
-
-```bash
-curl -u "YOUR_API_KEY:X" "https://YOUR_DOMAIN.freshservice.com/api/v2/ticket_form_fields" | \
-  python3 -c "import sys,json; [print(c['id'], c['value']) for f in json.load(sys.stdin)['ticket_fields'] if f['name']=='source' for c in f['choices']]"
-```
-
----
-
-## 5. Workspace Configuration
-
-**Note:** If your Freshservice instance uses multiple workspaces, API access is workspace-scoped.
-
-### Check Your Workspace:
-
-```bash
-curl -u "YOUR_API_KEY:X" "https://YOUR_DOMAIN.freshservice.com/api/v2/agents/me" | \
-  python3 -c "import sys,json; print('Workspace IDs:', json.load(sys.stdin)['agent']['workspace_ids'])"
-```
-
-### List Workspaces:
-
-```bash
-curl -u "YOUR_API_KEY:X" "https://YOUR_DOMAIN.freshservice.com/api/v2/workspaces"
-```
-
-If tickets are in a different workspace than your agent, you'll get `403` errors.
-
----
-
-## 6. API Endpoints Reference
-
-### Base URL
-```
-https://YOUR_DOMAIN.freshservice.com/api/v2
-```
-
-### Authentication
-```
-Basic Auth: API_KEY:X
-```
-
-### Endpoints Used by Golem
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| GET | `/agents/me` | Get current agent profile |
-| GET | `/tickets?filter=new_and_my_open` | List my open tickets |
-| GET | `/tickets/{id}` | Get single ticket |
-| POST | `/tickets` | Create ticket |
-| PUT | `/tickets/{id}` | Update ticket |
-| POST | `/tickets/{id}/notes` | Add note to ticket |
-| GET | `/ticket_form_fields` | Get ticket field definitions |
-| POST | `/ticket_fields/sources` | Create custom source |
-| GET | `/groups` | List agent groups |
-| GET | `/workspaces` | List workspaces |
-
-### Valid Filter Values for Tickets
-
-```
-new_and_my_open, watching, spam, deleted, archived
-```
-
-Note: `assigned_to_me` is NOT valid (despite being documented elsewhere).
-
----
-
-## 7. Common Errors and Solutions
-
-### 403 Forbidden - "You are not authorized to perform this action"
-
-**Causes:**
-1. Agent only has "Account Admin" role (no ticket permissions)
-2. Agent not assigned to correct workspace
-3. API key is incorrect or expired
-
-**Solution:** Add an agent role (IT Agent, IT Supervisor, etc.) with `manage_tickets` privilege.
-
-### 400 Validation Failed - Missing group_id
-
-**Cause:** Your Freshservice instance requires `group_id` for ticket creation.
-
-**Solution:** Include `group_id` in ticket creation payload. Get valid IDs from `/api/v2/groups`.
-
-### 400 Validation Failed - Invalid category
-
-**Cause:** Category value doesn't match configured options.
-
-**Solution:** Query `/api/v2/ticket_form_fields` to get valid category values for your instance.
-
-### 400 Validation Failed - Invalid filter
-
-**Cause:** Using unsupported filter value like `assigned_to_me`.
-
-**Solution:** Use `new_and_my_open` instead.
-
----
-
-## 8. Environment Variables
-
-Set these in `~/.golem/.env`:
-
-```bash
-# Freshservice Configuration
-FRESH_DOMAIN=your-instance.freshservice.com
-FRESH_API_KEY=your_api_key_here
-
-# Optional: Default values for ticket creation
-FRESH_DEFAULT_GROUP_ID=38000120203
-FRESH_DEFAULT_CATEGORY=Applications
-FRESH_SOURCE_ID=1002
-```
-
----
-
-## 9. Testing the Configuration
-
-Run these commands to verify everything is working:
-
-### Test Authentication:
-```bash
-golem-api fresh:test
-```
-
-Expected output:
-```
-✓ Connected to Freshworks
-  Found X tickets assigned to you
-```
-
-### List Your Tickets:
-```bash
-golem-api fresh:list
-```
-
-### Create a Test Ticket:
-```bash
-curl -X POST -u "$FRESH_API_KEY:X" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "subject": "API Test Ticket",
-    "description": "Testing API connectivity",
-    "email": "your@email.com",
-    "group_id": YOUR_GROUP_ID,
-    "category": "Applications",
-    "source": YOUR_SOURCE_ID,
-    "priority": 3,
-    "status": 2
-  }' \
-  "https://$FRESH_DOMAIN/api/v2/tickets"
-```
-
----
-
-## 10. Production Checklist
-
-Before deploying to production:
-
-- [ ] Create dedicated service account (don't use personal account)
-- [ ] Assign IT Agent/Supervisor role to service account
-- [ ] Generate API key for service account
-- [ ] Create "ACE (API)" custom source
-- [ ] Document group_id values for your teams
-- [ ] Document valid category values
-- [ ] Test ticket creation with all required fields
-- [ ] Test ticket updates and notes
-- [ ] Store API key securely (not in git)
-
----
-
-## Appendix: Our Sandbox Configuration
-
-**Domain:** `pearlriverresorthelpdesk-service-desk-sandbox.freshservice.com`
-
-**Agent Roles Required:**
-- Account Admin (for admin functions)
-- IT Operations (role_id: 38000126321)
-- IT Manager (role_id: 38000126322)
-
-**Group ID (Development):** `38000120203`
-
-**Categories:** `Hardware`, `Applications`, `Infrastructure`, `Security`
-
-**Custom Source:**
-- Name: `ACE (API)`
-- choice_id: `1002`
-
-**Workspace:**
-- ID: `2`
-- Name: `IT`

package/docs/HANDOFF.md

@@ -1,241 +0,0 @@
-# Golem Project Handoff
-
-## What Is This?
-
-Golem is a personal agentic workflow manager that integrates:
-- **Freshservice** (ticketing)
-- **Gitea** (issues/PRs/code)
-- **Claude Code** (AI-assisted development)
-- **Local state** (source of truth linking everything)
-
-It replaces the old `golem-cc` with a hyper-focused tool for your specific workflow.
-
-## Repository
-
-GitHub: https://github.com/daresTheDevil/golem (private)
-
-## Current State
-
-### Working
-- ✅ Freshservice API connection (sandbox instance)
-- ✅ Gitea API connection (dev.pearlriverresort.com)
-- ✅ `golem new` - create ticket in Fresh + Gitea with bi-directional links
-- ✅ `golem import` - import existing Fresh ticket, creates linked Gitea issue
-- ✅ Idempotency on import - won't create duplicate Gitea issues
-- ✅ `golem worktree` - create git worktree for ticket (works with/without remote)
-- ✅ `golem-api ticket:status X done` - resolves ticket in both Fresh and Gitea
-- ✅ Local state files in `.golem/tickets/*.yaml`
-- ✅ CLI installed globally (`golem` and `golem-api`)
-- ✅ Claude Code slash commands (`/golem:spec`, `/golem:plan`, `/golem:build`, etc.)
-- ✅ Conventional commit branch naming: `{type}/{ticketId}-{slug}` (e.g., `fix/INC-6-idempotency-check`)
-
-### Not Yet Tested
-- ⏳ `golem build` - run Claude in print mode loop
-- ⏳ `golem plan` - generate implementation plan
-- ⏳ `golem squash` - squash stage commits
-- ⏳ `golem pr` - create PR for ticket
-- ⏳ Full workflow: spec → plan → build loop
-
-### Known Issues
-- Labels on Gitea issues disabled (Gitea expects label IDs, not strings)
-- Can't delete Fresh tickets via API (need `delete_ticket` privilege)
-
-## Project Structure
-
-```
-/Users/dkay/code/golem-cc-new/
-├── bin/
-│   ├── golem              # Main bash CLI
-│   └── install.sh         # Global installer
-├── src/
-│   ├── api/
-│   │   ├── freshworks.ts  # Freshservice API client
-│   │   └── gitea.ts       # Gitea API client
-│   ├── sync/
-│   │   └── ticket-sync.ts # Import/sync logic
-│   ├── worktree/
-│   │   └── manager.ts     # Git worktree operations
-│   ├── cli/
-│   │   └── index.ts       # golem-api CLI commands
-│   └── types.ts           # TypeScript types
-├── commands/golem/        # Claude Code slash commands
-│   ├── spec.md
-│   ├── plan.md
-│   ├── build.md
-│   ├── simplify.md
-│   ├── status.md
-│   └── help.md
-├── golem/                 # Prompts and agents
-│   ├── agents/
-│   │   ├── spec-builder.md
-│   │   └── code-simplifier.md
-│   └── prompts/
-│       ├── PROMPT_build.md
-│       └── PROMPT_plan.md
-├── docs/
-│   ├── FRESHSERVICE_SETUP.md  # Detailed Fresh API setup guide
-│   └── HANDOFF.md             # This file
-└── .golem/
-    └── tickets/           # Local ticket state files
-```
-
-## Environment
-
-### Credentials Location
-```
-~/.golem/.env
-```
-
-### Required Environment Variables
-```bash
-# Freshworks/Freshservice
-FRESH_DOMAIN=pearlriverresorthelpdesk-service-desk-sandbox.freshservice.com
-FRESH_API_KEY=<redacted>
-
-# Freshservice defaults for ticket creation
-FRESH_DEFAULT_GROUP_ID=38000120203
-FRESH_DEFAULT_CATEGORY=Applications
-FRESH_SOURCE_ID=1002
-FRESH_DEFAULT_EMAIL=ace-bot@pearlriverresort.com
-
-# Gitea (on-prem)
-GITEA_URL=https://dev.pearlriverresort.com
-GITEA_TOKEN=<redacted>
-GITEA_ORG=CRDE
-GITEA_REPO=dashboard
-```
-
-### PATH Setup
-In `~/.zshrc`:
-```bash
-case ":$PATH:" in
-  *":$HOME/.local/bin:"*) ;;
-  *) export PATH="$HOME/.local/bin:$PATH" ;;
-esac
-```
-
-## Freshservice Configuration (IMPORTANT)
-
-See `docs/FRESHSERVICE_SETUP.md` for full details. Key points:
-
-1. **Agent needs both admin AND agent roles** - Account Admin alone can't access tickets via API
-2. **Required ticket fields for creation**: `status`, `group_id`, `category`, `email`, `source`
-3. **Required fields for closing**: `responder_id`, `resolution_notes`
-4. **Custom source created**: "ACE (API)" with `choice_id: 1002`
-5. **Valid filter**: Use `new_and_my_open` not `assigned_to_me`
-
-### Your Roles
-- Account Admin (38000126263)
-- IT Operations (38000126321)
-- IT Manager (38000126322)
-
-### Key IDs
-- Agent ID (dkay): `38001086138`
-- Group ID (Development): `38000120203`
-- Source ID (ACE API): `1002`
-- Workspace ID: `2` (IT)
-
-## Test Data Created
-
-### Fresh Tickets (Sandbox)
-- INC-2: "Test for API" → linked to Gitea #1
-- INC-3: "Ticket created from API" (no Gitea link)
-- INC-4: "Ticket created via Golem" → linked to Gitea #3
-- INC-5: "Test golem new command" → linked to Gitea #5
-- INC-6: "Add idempotency check..." → linked to Gitea #6 (RESOLVED)
-- INC-7: "Test ticket close flow" → linked to Gitea #7 (RESOLVED)
-
-### Gitea Issues (dashboard repo)
-- #1: [INC-2] Test for API
-- #3: [INC-4] Ticket created via API
-- #5: [INC-5] Test golem new command
-- #6: [INC-6] Add idempotency check to prevent duplicate Gitea issues
-- #7: [INC-7] Test ticket close flow
-
-### Test Project
-- `~/code/test-worktree-project` - Used for testing worktree creation
-- Has fake tickets TEST-1, TEST-2, TEST-3 with worktrees
-
-## Commands Reference
-
-### Terminal
-```bash
-golem help              # Show all commands
-golem version           # Show version
-golem init              # Initialize golem in current project
-
-golem new "Subject"     # Create new ticket (interactive prompts for type/slug)
-golem import INC-XXX    # Import existing Fresh ticket
-golem worktree INC-XXX  # Create/switch to worktree for ticket
-golem worktrees         # List all worktrees
-golem status [INC-XXX]  # Show ticket or project status
-
-golem-api fresh:test    # Test Fresh connection
-golem-api fresh:list    # List your tickets
-golem-api gitea:test    # Test Gitea connection
-golem-api ticket:list   # List tracked tickets
-golem-api ticket:get INC-XXX
-golem-api ticket:status INC-XXX done --note "Resolution message"
-```
-
-### Claude Code
-```
-/golem:help      # Show help
-/golem:status    # Show current status
-/golem:spec      # Define specs (interactive)
-/golem:plan      # Create implementation plan
-/golem:build     # Run one build iteration
-/golem:simplify  # Run code simplifier
-```
-
-## Next Steps
-
-1. **Test the full workflow**: spec → plan → build loop
-2. **Test `golem squash`** - squash commits before PR
-3. **Test `golem pr`** - create PR for ticket
-4. **Production setup**: Same Fresh config steps on prod instance
-5. **Consider**: Adding label support to Gitea (need to create labels first, then use IDs)
-
-## Build Commands
-
-```bash
-cd /Users/dkay/code/golem-cc-new
-pnpm install      # Install deps
-pnpm build        # Compile TypeScript
-./bin/install.sh  # Reinstall globally (after changes)
-```
-
-## Recent Fixes (2026-02-04)
-
-### Worktree Creation
-- Fixed: Now works for repos without remotes (falls back to local branch → HEAD)
-- Fixed: `set -e` bug where missing local `.env` caused silent exit
-
-### Freshservice Integration
-- Fixed: `golem new` now includes all required fields (status, source, group_id, category, email)
-- Fixed: Closing tickets now sets `responder_id` (current agent) and `resolution_notes`
-- Uses status 4 (Resolved) instead of 5 (Closed) for simpler workflow
-
-### Idempotency
-- Added `findIssueByTicketId()` to Gitea client
-- Import checks local state first, then searches Gitea before creating
-- Re-importing won't create duplicate issues
-
-## Useful Debug Commands
-
-```bash
-# Check Fresh ticket details
-curl -s -u "API_KEY:X" "https://DOMAIN/api/v2/tickets/ID" | python3 -m json.tool
-
-# Check Fresh ticket notes
-curl -s -u "API_KEY:X" "https://DOMAIN/api/v2/tickets/ID/conversations"
-
-# Check Gitea issues
-curl -s -H "Authorization: token TOKEN" "https://dev.pearlriverresort.com/api/v1/repos/CRDE/dashboard/issues?state=all"
-
-# Check local ticket state
-cat .golem/tickets/INC-2.yaml
-
-# Get your agent ID
-curl -s -u "API_KEY:X" "https://DOMAIN/api/v2/agents/me" | python3 -c "import sys,json; print(json.load(sys.stdin)['agent']['id'])"
-```