@damper/cli 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,202 @@
+# @damper/cli
+
+Agent orchestration CLI for working on [Damper](https://usedamper.com) roadmap tasks with Claude Code.
+
+## What it does
+
+1. **Picks a task** from your Damper roadmap (interactive or by ID)
+2. **Creates an isolated git worktree** for the task
+3. **Bootstraps context** - fetches task details, project docs, and critical rules from Damper
+4. **Launches Claude Code** with full context ready to go
+
+Claude then handles the task lifecycle via Damper MCP - logging commits, adding notes, and completing/abandoning tasks.
+
+## Installation
+
+```bash
+# Run directly with npx (recommended)
+npx @damper/cli
+
+# Or install globally
+npm install -g @damper/cli
+```
+
+### Prerequisites
+
+- [Claude Code CLI](https://claude.ai/code) installed
+- A Damper account with an API key
+
+## Quick Start
+
+```bash
+# First time? Run setup to configure MCP and API key
+npx @damper/cli setup
+
+# Start working on a task
+npx @damper/cli
+```
+
+## Commands
+
+### `npx @damper/cli` (default)
+
+Interactive task picker. Shows:
+- **In Progress** - Tasks with existing worktrees you can resume
+- **Available** - Planned tasks from your roadmap
+
+```bash
+npx @damper/cli                    # Interactive picker
+npx @damper/cli --task 42          # Start specific task
+npx @damper/cli --type bug         # Filter by type
+npx @damper/cli --status planned   # Filter by status
+```
+
+### `npx @damper/cli setup`
+
+Configure Damper MCP in Claude Code. Run this first if you haven't set up MCP yet.
+
+- Checks if Claude CLI is installed
+- Configures `~/.claude/settings.json` with Damper MCP
+- Prompts for API key if not in environment
+
+### `npx @damper/cli status`
+
+Show all tracked worktrees and their task status.
+
+```
+Tracked Worktrees:
+
+myproject (current)
+  /Users/me/projects/myproject
+
+  ● #42 [in_progress]
+    Path: myproject-oauth-support
+    Branch: feature/oauth-support
+    Created: 2/5/2025
+```
+
+### `npx @damper/cli cleanup`
+
+Remove worktrees for completed or abandoned tasks. Interactive selection with auto-detection of:
+- Completed tasks
+- Abandoned tasks (unlocked in Damper)
+- Missing worktree directories
+
+## Workflow
+
+### Starting a New Task
+
+```
+$ npx @damper/cli
+
+? Select a task to work on:
+  --- Available Tasks ---
+❯ #42 Add OAuth support [feature] !
+  #38 Fix login timeout [bug] ~
+
+✓ Task locked in Damper
+✓ Created worktree: ../myproject-oauth-support
+✓ Created TASK_CONTEXT.md
+✓ Updated CLAUDE.md with task section
+
+Starting Claude Code for task #42: Add OAuth support
+```
+
+### Resuming Work
+
+```
+$ npx @damper/cli
+
+? Select a task to work on:
+  --- In Progress (your worktrees) ---
+❯ #42 Add OAuth support [feature] !
+    Worktree: myproject-oauth-support
+  --- Available Tasks ---
+  #38 Fix login timeout [bug] ~
+
+✓ Resuming: #42 Add OAuth support
+✓ Updated TASK_CONTEXT.md with latest notes
+```
+
+### Generated Files
+
+The CLI creates these files in the worktree:
+
+**`TASK_CONTEXT.md`** - Full task context for Claude:
+- Critical rules (must-follow patterns)
+- Damper workflow instructions
+- Task description and implementation plan
+- Previous session notes and commits
+- Project architecture docs
+- Available templates and modules
+- Linked customer feedback
+
+**`CLAUDE.md`** (appended) - Task-specific section pointing to TASK_CONTEXT.md
+
+### Task Lifecycle (handled by Claude via MCP)
+
+Once Claude is running, it handles:
+- `add_commit` - Log commits to Damper
+- `add_note` - Record decisions and progress
+- `complete_task` - Mark done with summary
+- `abandon_task` - Hand off with notes for next agent
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `DAMPER_API_KEY` | Your Damper API key (or configure via `setup`) |
+| `DAMPER_API_URL` | API URL override (default: `https://api.usedamper.com`) |
+
+## How it Works
+
+### Worktree Isolation
+
+Each task gets its own git worktree:
+```
+myproject/                    # Main repo
+../myproject-oauth-support/   # Task #42 worktree
+../myproject-fix-login/       # Task #38 worktree
+```
+
+The CLI automatically:
+- Creates the worktree with a feature branch
+- Symlinks `node_modules` (detects monorepo structure)
+- Copies `.env` files
+
+### Context from Damper
+
+The CLI fetches from Damper:
+- Task details (description, plan, subtasks)
+- Project context (architecture, conventions)
+- Critical rules (shown prominently to Claude)
+- Templates (code patterns to follow)
+- Modules (monorepo structure)
+- Previous agent notes (for continuity)
+
+This context survives Claude conversation compaction because it's in local files.
+
+### State Tracking
+
+Worktree-to-task mappings are stored in `~/.damper/worktrees.json`. This enables:
+- Showing "resume" options for in-progress tasks
+- Detecting stale worktrees for cleanup
+- Tracking across multiple projects
+
+## Parallel Work
+
+Run multiple instances in different terminals:
+
+```bash
+# Terminal 1
+npx @damper/cli --task 42
+
+# Terminal 2
+npx @damper/cli --task 38
+```
+
+Each task gets its own worktree and Claude session.
+
+## License
+
+MIT

package/dist/commands/cleanup.js

@@ -1,9 +1,22 @@
 import * as fs from 'node:fs';
 import { confirm, checkbox } from '@inquirer/prompts';
+import { execa } from 'execa';
 import pc from 'picocolors';
 import { getWorktrees, cleanupStaleWorktrees, removeWorktree } from '../services/state.js';
 import { createDamperApi } from '../services/damper-api.js';
 import { removeWorktreeDir } from '../services/worktree.js';
+async function hasUncommittedChanges(worktreePath) {
+    try {
+        const { stdout } = await execa('git', ['status', '--porcelain'], {
+            cwd: worktreePath,
+            stdio: 'pipe',
+        });
+        return stdout.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}
 export async function cleanupCommand() {
     // Clean up stale entries first
     const stale = cleanupStaleWorktrees();
@@ -37,6 +50,8 @@ export async function cleanupCommand() {
             });
             continue;
         }
+        // Check for uncommitted changes
+        const uncommitted = await hasUncommittedChanges(wt.path);
         if (api) {
             try {
                 const task = await api.getTask(wt.taskId);
@@ -45,6 +60,7 @@ export async function cleanupCommand() {
                         worktree: wt,
                         task,
                         reason: 'completed',
+                        hasUncommittedChanges: uncommitted,
                     });
                 }
                 else if (task.status === 'planned' && !task.lockedBy) {
@@ -53,6 +69,7 @@ export async function cleanupCommand() {
                         worktree: wt,
                         task,
                         reason: 'abandoned',
+                        hasUncommittedChanges: uncommitted,
                     });
                 }
             }
@@ -61,6 +78,7 @@ export async function cleanupCommand() {
                 candidates.push({
                     worktree: wt,
                     reason: 'manual',
+                    hasUncommittedChanges: uncommitted,
                 });
             }
         }
@@ -69,6 +87,7 @@ export async function cleanupCommand() {
             candidates.push({
                 worktree: wt,
                 reason: 'manual',
+                hasUncommittedChanges: uncommitted,
             });
         }
     }
@@ -99,10 +118,15 @@ export async function cleanupCommand() {
                 reasonBadge = pc.dim('[manual]');
                 break;
         }
+        // Warning for uncommitted changes
+        const uncommittedWarning = c.hasUncommittedChanges
+            ? pc.red(' ⚠ uncommitted changes')
+            : '';
         return {
-            name: `${description} ${reasonBadge}\n    ${pc.dim(worktreeName)}`,
+            name: `${description} ${reasonBadge}${uncommittedWarning}\n    ${pc.dim(worktreeName)}`,
             value: c,
-            checked: c.reason === 'completed' || c.reason === 'missing',
+            // Don't auto-check if there are uncommitted changes
+            checked: (c.reason === 'completed' || c.reason === 'missing') && !c.hasUncommittedChanges,
         };
     });
     const selected = await checkbox({
@@ -114,9 +138,17 @@ export async function cleanupCommand() {
         console.log(pc.dim('\nNo worktrees selected. Nothing to clean up.\n'));
         return;
     }
+    // Check for uncommitted changes in selected worktrees
+    const withUncommitted = selected.filter(c => c.hasUncommittedChanges);
+    if (withUncommitted.length > 0) {
+        console.log(pc.yellow(`\n⚠ Warning: ${withUncommitted.length} worktree(s) have uncommitted changes that will be lost!`));
+    }
     // Confirm
+    const confirmMessage = withUncommitted.length > 0
+        ? `Remove ${selected.length} worktree(s)? (${withUncommitted.length} with uncommitted changes)`
+        : `Remove ${selected.length} worktree(s)?`;
     const confirmed = await confirm({
-        message: `Remove ${selected.length} worktree(s)?`,
+        message: confirmMessage,
         default: false,
     });
     if (!confirmed) {

package/dist/commands/setup.js

@@ -17,7 +17,7 @@ export async function setupCommand() {
     const apiKey = getConfiguredApiKey();
     if (mcpConfigured && apiKey) {
         console.log(pc.green('✓ Damper MCP configured'));
-        console.log(pc.dim(`  API key: ${apiKey.slice(0, 8)}...${apiKey.slice(-4)}`));
+        console.log(pc.dim(`  API key: ${'*'.repeat(12)} (${apiKey.length} chars)`));
         // Verify the API key works
         console.log(pc.dim('\nVerifying API key...'));
         try {

package/dist/services/worktree.js

@@ -165,16 +165,19 @@ export async function createWorktree(options) {
     }
     // Copy .env files
     const envFiles = findEnvFiles(projectRoot);
-    for (const envFile of envFiles) {
-        const source = path.join(projectRoot, envFile);
-        const target = path.join(worktreePath, envFile);
-        // Ensure parent directory exists
-        const targetDir = path.dirname(target);
-        if (!fs.existsSync(targetDir)) {
-            fs.mkdirSync(targetDir, { recursive: true });
+    if (envFiles.length > 0) {
+        console.log(pc.dim(`Copying ${envFiles.length} .env file(s) to worktree...`));
+        for (const envFile of envFiles) {
+            const source = path.join(projectRoot, envFile);
+            const target = path.join(worktreePath, envFile);
+            // Ensure parent directory exists
+            const targetDir = path.dirname(target);
+            if (!fs.existsSync(targetDir)) {
+                fs.mkdirSync(targetDir, { recursive: true });
+            }
+            console.log(pc.dim(`  ${envFile}`));
+            await fs.promises.copyFile(source, target);
         }
-        console.log(pc.dim(`Copying ${envFile}...`));
-        await fs.promises.copyFile(source, target);
     }
     // Save to state
     const worktreeState = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@damper/cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "CLI tool for orchestrating Damper task workflows with Claude Code",
   "author": "Damper <hello@usedamper.com>",
   "repository": {