@damper/cli 0.1.0

package/dist/commands/cleanup.d.ts

@@ -0,0 +1 @@
+export declare function cleanupCommand(): Promise<void>;

package/dist/commands/cleanup.js

@@ -0,0 +1,149 @@
+import * as fs from 'node:fs';
+import { confirm, checkbox } from '@inquirer/prompts';
+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';
+export async function cleanupCommand() {
+    // Clean up stale entries first
+    const stale = cleanupStaleWorktrees();
+    if (stale.length > 0) {
+        console.log(pc.dim(`Removed ${stale.length} stale worktree reference(s)`));
+    }
+    const worktrees = getWorktrees();
+    if (worktrees.length === 0) {
+        console.log(pc.yellow('\nNo tracked worktrees found.'));
+        return;
+    }
+    // Try to connect to Damper for task status
+    let api;
+    try {
+        api = createDamperApi();
+    }
+    catch {
+        console.log(pc.yellow('\nWarning: Could not connect to Damper API (no API key).'));
+        console.log(pc.dim('Will show all worktrees for manual selection.\n'));
+    }
+    // Identify cleanup candidates
+    const candidates = [];
+    console.log(pc.dim('\nAnalyzing worktrees...'));
+    for (const wt of worktrees) {
+        const exists = fs.existsSync(wt.path);
+        if (!exists) {
+            // Worktree directory is missing
+            candidates.push({
+                worktree: wt,
+                reason: 'missing',
+            });
+            continue;
+        }
+        if (api) {
+            try {
+                const task = await api.getTask(wt.taskId);
+                if (task.status === 'done') {
+                    candidates.push({
+                        worktree: wt,
+                        task,
+                        reason: 'completed',
+                    });
+                }
+                else if (task.status === 'planned' && !task.lockedBy) {
+                    // Task was abandoned (planned and not locked)
+                    candidates.push({
+                        worktree: wt,
+                        task,
+                        reason: 'abandoned',
+                    });
+                }
+            }
+            catch {
+                // Could not fetch task - might be deleted
+                candidates.push({
+                    worktree: wt,
+                    reason: 'manual',
+                });
+            }
+        }
+        else {
+            // No API - show all for manual selection
+            candidates.push({
+                worktree: wt,
+                reason: 'manual',
+            });
+        }
+    }
+    if (candidates.length === 0) {
+        console.log(pc.green('\n✓ All worktrees are for active tasks. Nothing to clean up.\n'));
+        return;
+    }
+    // Show candidates and let user select
+    console.log(pc.bold('\nWorktrees available for cleanup:\n'));
+    const choices = candidates.map(c => {
+        const worktreeName = c.worktree.path.split('/').pop() || c.worktree.path;
+        let description = `#${c.worktree.taskId}`;
+        if (c.task) {
+            description += ` - ${c.task.title}`;
+        }
+        let reasonBadge = '';
+        switch (c.reason) {
+            case 'completed':
+                reasonBadge = pc.green('[completed]');
+                break;
+            case 'abandoned':
+                reasonBadge = pc.yellow('[abandoned]');
+                break;
+            case 'missing':
+                reasonBadge = pc.red('[missing]');
+                break;
+            case 'manual':
+                reasonBadge = pc.dim('[manual]');
+                break;
+        }
+        return {
+            name: `${description} ${reasonBadge}\n    ${pc.dim(worktreeName)}`,
+            value: c,
+            checked: c.reason === 'completed' || c.reason === 'missing',
+        };
+    });
+    const selected = await checkbox({
+        message: 'Select worktrees to remove:',
+        choices,
+        pageSize: 10,
+    });
+    if (selected.length === 0) {
+        console.log(pc.dim('\nNo worktrees selected. Nothing to clean up.\n'));
+        return;
+    }
+    // Confirm
+    const confirmed = await confirm({
+        message: `Remove ${selected.length} worktree(s)?`,
+        default: false,
+    });
+    if (!confirmed) {
+        console.log(pc.dim('\nCancelled.\n'));
+        return;
+    }
+    // Remove selected worktrees
+    console.log();
+    for (const candidate of selected) {
+        const { worktree } = candidate;
+        const worktreeName = worktree.path.split('/').pop() || worktree.path;
+        try {
+            if (candidate.reason === 'missing') {
+                // Just remove from state
+                removeWorktree(worktree.taskId);
+                console.log(pc.green(`✓ Removed reference: ${worktreeName}`));
+            }
+            else {
+                // Remove actual worktree
+                await removeWorktreeDir(worktree.path, worktree.projectRoot);
+                console.log(pc.green(`✓ Removed: ${worktreeName}`));
+            }
+        }
+        catch (err) {
+            const error = err;
+            console.log(pc.red(`✗ Failed to remove ${worktreeName}: ${error.message}`));
+        }
+    }
+    console.log();
+}

package/dist/commands/setup.d.ts

@@ -0,0 +1 @@
+export declare function setupCommand(): Promise<void>;

package/dist/commands/setup.js

@@ -0,0 +1,67 @@
+import pc from 'picocolors';
+import { isDamperMcpConfigured, getConfiguredApiKey, setupDamperMcp, isClaudeInstalled, } from '../services/claude.js';
+import { createDamperApi } from '../services/damper-api.js';
+export async function setupCommand() {
+    console.log(pc.bold('\n@damper/cli Setup\n'));
+    // Check Claude CLI
+    const claudeInstalled = await isClaudeInstalled();
+    if (!claudeInstalled) {
+        console.log(pc.red('✗ Claude Code CLI not found'));
+        console.log(pc.dim('  Install it with: npm install -g @anthropic-ai/claude-code\n'));
+    }
+    else {
+        console.log(pc.green('✓ Claude Code CLI installed'));
+    }
+    // Check MCP configuration
+    const mcpConfigured = isDamperMcpConfigured();
+    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)}`));
+        // Verify the API key works
+        console.log(pc.dim('\nVerifying API key...'));
+        try {
+            const api = createDamperApi(apiKey);
+            const { project } = await api.listTasks({ limit: 1 });
+            console.log(pc.green(`✓ Connected to project: ${project}`));
+        }
+        catch (err) {
+            const error = err;
+            console.log(pc.red(`✗ API key verification failed: ${error.message}`));
+            console.log(pc.dim('  You may need to reconfigure with a valid key.\n'));
+            // Offer to reconfigure
+            const key = await setupDamperMcp();
+            if (key) {
+                console.log(pc.green('\n✓ Setup complete!\n'));
+            }
+            return;
+        }
+        console.log(pc.green('\n✓ All checks passed! You\'re ready to use @damper/cli.\n'));
+        console.log(pc.dim('Run `npx @damper/cli` to start working on a task.\n'));
+        return;
+    }
+    // Not configured - run setup
+    if (!mcpConfigured) {
+        console.log(pc.yellow('○ Damper MCP not configured'));
+    }
+    else if (!apiKey) {
+        console.log(pc.yellow('○ Damper MCP configured but missing API key'));
+    }
+    const key = await setupDamperMcp();
+    if (key) {
+        // Verify the new key
+        console.log(pc.dim('\nVerifying API key...'));
+        try {
+            const api = createDamperApi(key);
+            const { project } = await api.listTasks({ limit: 1 });
+            console.log(pc.green(`✓ Connected to project: ${project}`));
+            console.log(pc.green('\n✓ Setup complete! You\'re ready to use @damper/cli.\n'));
+            console.log(pc.dim('Run `npx @damper/cli` to start working on a task.\n'));
+        }
+        catch (err) {
+            const error = err;
+            console.log(pc.red(`✗ API key verification failed: ${error.message}`));
+            console.log(pc.dim('  Please check your API key and try again.\n'));
+        }
+    }
+}

package/dist/commands/start.d.ts

@@ -0,0 +1,6 @@
+export interface StartOptions {
+    taskId?: string;
+    type?: 'bug' | 'feature' | 'improvement' | 'task';
+    status?: 'planned' | 'in_progress' | 'done' | 'all';
+}
+export declare function startCommand(options: StartOptions): Promise<void>;

package/dist/commands/start.js

@@ -0,0 +1,139 @@
+import * as fs from 'node:fs';
+import pc from 'picocolors';
+import { createDamperApi } from '../services/damper-api.js';
+import { createWorktree, getGitRoot } from '../services/worktree.js';
+import { bootstrapContext, refreshContext } from '../services/context-bootstrap.js';
+import { pickTask } from '../ui/task-picker.js';
+import { launchClaude, isClaudeInstalled, ensureMcpConfigured } from '../services/claude.js';
+import { getWorktreesForProject, cleanupStaleWorktrees } from '../services/state.js';
+export async function startCommand(options) {
+    // Check Claude CLI first
+    const claudeInstalled = await isClaudeInstalled();
+    if (!claudeInstalled) {
+        console.log(pc.red('\nError: Claude Code CLI not found.'));
+        console.log(pc.dim('Install it with: npm install -g @anthropic-ai/claude-code\n'));
+        process.exit(1);
+    }
+    // Ensure MCP is configured (will prompt for setup if not)
+    // This also handles API key setup
+    const apiKey = await ensureMcpConfigured();
+    // Get project root (git root)
+    let projectRoot;
+    try {
+        projectRoot = await getGitRoot(process.cwd());
+    }
+    catch {
+        console.log(pc.red('\nError: Not in a git repository.'));
+        console.log(pc.dim('Run this command from within a git repository.\n'));
+        process.exit(1);
+    }
+    // Create API client with the configured key
+    const api = createDamperApi(apiKey);
+    // Clean up stale worktrees
+    const stale = cleanupStaleWorktrees();
+    if (stale.length > 0) {
+        console.log(pc.dim(`Cleaned up ${stale.length} stale worktree reference(s)`));
+    }
+    // Get existing worktrees for this project
+    const worktrees = getWorktreesForProject(projectRoot);
+    let taskId;
+    let taskTitle;
+    let isResume = false;
+    let worktreePath;
+    if (options.taskId) {
+        // Direct task selection
+        taskId = options.taskId;
+        const task = await api.getTask(taskId);
+        taskTitle = task.title;
+        // Check if we have an existing worktree for this task
+        const existingWorktree = worktrees.find(w => w.taskId === taskId);
+        if (existingWorktree && fs.existsSync(existingWorktree.path)) {
+            isResume = true;
+            worktreePath = existingWorktree.path;
+            console.log(pc.cyan(`\nResuming task #${taskId}: ${taskTitle}`));
+        }
+        else {
+            console.log(pc.cyan(`\nStarting task #${taskId}: ${taskTitle}`));
+        }
+    }
+    else {
+        // Interactive task picker
+        const result = await pickTask({
+            api,
+            worktrees,
+            typeFilter: options.type,
+            statusFilter: options.status,
+        });
+        if (!result) {
+            process.exit(0);
+        }
+        taskId = result.task.id;
+        taskTitle = result.task.title;
+        isResume = result.isResume;
+        if (result.worktree) {
+            worktreePath = result.worktree.path;
+        }
+    }
+    if (isResume && worktreePath) {
+        // Resume existing worktree
+        console.log(pc.green(`\n✓ Resuming: #${taskId} ${taskTitle}`));
+        console.log(pc.dim(`  Worktree: ${worktreePath}`));
+        // Refresh context with latest from Damper
+        console.log(pc.dim('\nRefreshing context from Damper...'));
+        await refreshContext({
+            api,
+            taskId,
+            worktreePath,
+        });
+        console.log(pc.green('✓ Updated TASK_CONTEXT.md with latest notes'));
+    }
+    else {
+        // New task - lock it first
+        console.log(pc.dim('\nLocking task in Damper...'));
+        try {
+            await api.startTask(taskId);
+            console.log(pc.green('✓ Task locked'));
+        }
+        catch (err) {
+            const error = err;
+            if (error.lockInfo) {
+                console.log(pc.yellow(`\n⚠️  Task is locked by "${error.lockInfo.lockedBy}" since ${error.lockInfo.lockedAt}`));
+                console.log(pc.dim('Use --force to take over the lock (if the other agent abandoned it).\n'));
+                process.exit(1);
+            }
+            throw err;
+        }
+        // Create worktree
+        console.log(pc.dim('\nSetting up worktree...'));
+        const worktreeResult = await createWorktree({
+            taskId,
+            taskTitle,
+            projectRoot,
+        });
+        worktreePath = worktreeResult.path;
+        if (worktreeResult.isNew) {
+            console.log(pc.green(`✓ Created worktree: ${worktreePath}`));
+            console.log(pc.dim(`  Branch: ${worktreeResult.branch}`));
+        }
+        else {
+            console.log(pc.green(`✓ Using existing worktree: ${worktreePath}`));
+        }
+        // Bootstrap context
+        console.log(pc.dim('\nBootstrapping context from Damper...'));
+        const bootstrapResult = await bootstrapContext({
+            api,
+            taskId,
+            worktreePath,
+        });
+        console.log(pc.green(`✓ Created ${bootstrapResult.taskContextPath}`));
+        if (bootstrapResult.claudeMdUpdated) {
+            console.log(pc.green('✓ Updated CLAUDE.md with task section'));
+        }
+    }
+    // Launch Claude
+    await launchClaude({
+        cwd: worktreePath,
+        taskId,
+        taskTitle,
+    });
+}

package/dist/commands/status.d.ts

@@ -0,0 +1 @@
+export declare function statusCommand(): Promise<void>;

package/dist/commands/status.js

@@ -0,0 +1,74 @@
+import * as fs from 'node:fs';
+import pc from 'picocolors';
+import { getWorktrees, cleanupStaleWorktrees } from '../services/state.js';
+import { createDamperApi } from '../services/damper-api.js';
+import { getGitRoot } from '../services/worktree.js';
+export async function statusCommand() {
+    // Clean up stale entries first
+    const stale = cleanupStaleWorktrees();
+    if (stale.length > 0) {
+        console.log(pc.dim(`Cleaned up ${stale.length} stale worktree reference(s)\n`));
+    }
+    // Get current project root
+    let projectRoot;
+    try {
+        projectRoot = await getGitRoot(process.cwd());
+    }
+    catch {
+        // Not in a git repo - show all worktrees
+    }
+    const worktrees = getWorktrees();
+    if (worktrees.length === 0) {
+        console.log(pc.yellow('\nNo tracked worktrees found.'));
+        console.log(pc.dim('Use `npx @damper/cli` to start working on a task.\n'));
+        return;
+    }
+    // Try to fetch task statuses from Damper
+    let api;
+    try {
+        api = createDamperApi();
+    }
+    catch {
+        // No API key - show worktrees without status
+    }
+    console.log(pc.bold('\nTracked Worktrees:\n'));
+    // Group by project
+    const byProject = new Map();
+    for (const wt of worktrees) {
+        const project = wt.projectRoot;
+        if (!byProject.has(project)) {
+            byProject.set(project, []);
+        }
+        byProject.get(project).push(wt);
+    }
+    for (const [project, projectWorktrees] of byProject) {
+        const isCurrent = projectRoot && project === projectRoot;
+        const projectName = project.split('/').pop() || project;
+        console.log(pc.bold(`${projectName}${isCurrent ? pc.cyan(' (current)') : ''}`));
+        console.log(pc.dim(`  ${project}`));
+        console.log();
+        for (const wt of projectWorktrees) {
+            const exists = fs.existsSync(wt.path);
+            const worktreeName = wt.path.split('/').pop() || wt.path;
+            // Try to get task status
+            let taskStatus = '';
+            if (api) {
+                try {
+                    const task = await api.getTask(wt.taskId);
+                    const statusColor = task.status === 'done' ? pc.green : task.status === 'in_progress' ? pc.yellow : pc.dim;
+                    taskStatus = statusColor(`[${task.status}]`);
+                }
+                catch {
+                    taskStatus = pc.dim('[unknown]');
+                }
+            }
+            const statusIcon = exists ? pc.green('●') : pc.red('○');
+            console.log(`  ${statusIcon} ${pc.cyan(`#${wt.taskId}`)} ${taskStatus}`);
+            console.log(`    ${pc.dim('Path:')} ${worktreeName}`);
+            console.log(`    ${pc.dim('Branch:')} ${wt.branch}`);
+            console.log(`    ${pc.dim('Created:')} ${new Date(wt.createdAt).toLocaleDateString()}`);
+            console.log();
+        }
+    }
+    console.log(pc.dim('Use `npx @damper/cli cleanup` to remove worktrees for completed tasks.\n'));
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+import pc from 'picocolors';
+import { startCommand } from './commands/start.js';
+import { statusCommand } from './commands/status.js';
+import { cleanupCommand } from './commands/cleanup.js';
+import { setupCommand } from './commands/setup.js';
+const VERSION = '0.1.0';
+function showHelp() {
+    console.log(`
+${pc.bold('@damper/cli')} - Agent orchestration for Damper tasks
+
+${pc.bold('Usage:')}
+  npx @damper/cli                    Start working on a task (interactive picker)
+  npx @damper/cli setup              Configure Damper MCP and API key
+  npx @damper/cli status             Show all in-progress worktrees
+  npx @damper/cli cleanup            Remove worktrees for completed tasks
+
+${pc.bold('Options:')}
+  --task <id>                        Work on a specific task
+  --type <type>                      Filter by type: bug, feature, improvement, task
+  --status <status>                  Filter by status: planned, in_progress, done, all
+  -h, --help                         Show this help message
+  -v, --version                      Show version
+
+${pc.bold('Environment:')}
+  DAMPER_API_KEY                     API key (or configure via 'setup' command)
+
+${pc.bold('Examples:')}
+  npx @damper/cli setup              # First-time setup
+  npx @damper/cli                    # Interactive task picker
+  npx @damper/cli --task 42          # Start specific task
+  npx @damper/cli --type bug         # Show only bugs
+  npx @damper/cli status             # List all worktrees
+  npx @damper/cli cleanup            # Clean up completed tasks
+
+${pc.bold('Workflow:')}
+  1. CLI picks task from Damper roadmap
+  2. Creates isolated git worktree
+  3. Bootstraps context (TASK_CONTEXT.md)
+  4. Launches Claude Code
+  5. Claude handles task lifecycle via MCP
+
+${pc.dim('More info: https://usedamper.com/docs/cli')}
+`);
+}
+function showVersion() {
+    console.log(`@damper/cli v${VERSION}`);
+}
+function parseArgs(args) {
+    const result = {
+        options: {},
+        help: false,
+        version: false,
+    };
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '-h' || arg === '--help') {
+            result.help = true;
+        }
+        else if (arg === '-v' || arg === '--version') {
+            result.version = true;
+        }
+        else if (arg === '--task') {
+            result.options.taskId = args[++i];
+        }
+        else if (arg === '--type') {
+            const type = args[++i];
+            if (type && ['bug', 'feature', 'improvement', 'task'].includes(type)) {
+                result.options.type = type;
+            }
+        }
+        else if (arg === '--status') {
+            const status = args[++i];
+            if (status && ['planned', 'in_progress', 'done', 'all'].includes(status)) {
+                result.options.status = status;
+            }
+        }
+        else if (!arg.startsWith('-') && !result.command) {
+            result.command = arg;
+        }
+    }
+    return result;
+}
+async function main() {
+    const args = process.argv.slice(2);
+    const { command, options, help, version } = parseArgs(args);
+    if (version) {
+        showVersion();
+        return;
+    }
+    if (help) {
+        showHelp();
+        return;
+    }
+    try {
+        switch (command) {
+            case 'setup':
+                await setupCommand();
+                break;
+            case 'status':
+                await statusCommand();
+                break;
+            case 'cleanup':
+                await cleanupCommand();
+                break;
+            case undefined:
+            case 'start':
+                await startCommand(options);
+                break;
+            default:
+                console.log(pc.red(`Unknown command: ${command}`));
+                console.log(pc.dim('Run with --help for usage information.\n'));
+                process.exit(1);
+        }
+    }
+    catch (err) {
+        const error = err;
+        console.error(pc.red(`\nError: ${error.message}`));
+        if (process.env.DEBUG) {
+            console.error(error.stack);
+        }
+        process.exit(1);
+    }
+}
+main();

package/dist/services/claude.d.ts

@@ -0,0 +1,44 @@
+interface McpServerConfig {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+}
+/**
+ * Check if Damper MCP is configured in Claude settings
+ */
+export declare function isDamperMcpConfigured(): boolean;
+/**
+ * Get the current API key from MCP config or environment
+ */
+export declare function getConfiguredApiKey(): string | undefined;
+/**
+ * Get the recommended MCP configuration
+ */
+export declare function getDamperMcpConfig(apiKey?: string): McpServerConfig;
+/**
+ * Configure Damper MCP in Claude settings
+ */
+export declare function configureDamperMcp(apiKey: string): void;
+/**
+ * Interactive setup for Damper MCP
+ * Returns the API key (either existing or newly entered)
+ */
+export declare function setupDamperMcp(): Promise<string | null>;
+/**
+ * Ensure MCP is configured, offering to set it up if not
+ * Returns the API key to use
+ */
+export declare function ensureMcpConfigured(): Promise<string>;
+/**
+ * Launch Claude Code in a directory
+ */
+export declare function launchClaude(options: {
+    cwd: string;
+    taskId: string;
+    taskTitle: string;
+}): Promise<void>;
+/**
+ * Check if Claude Code CLI is installed
+ */
+export declare function isClaudeInstalled(): Promise<boolean>;
+export {};