@damper/cli 0.1.0

package/dist/services/claude.js

@@ -0,0 +1,221 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { execa } from 'execa';
+import { confirm, password } from '@inquirer/prompts';
+import pc from 'picocolors';
+const CLAUDE_SETTINGS_DIR = path.join(os.homedir(), '.claude');
+const CLAUDE_SETTINGS_FILE = path.join(CLAUDE_SETTINGS_DIR, 'settings.json');
+/**
+ * Check if Damper MCP is configured in Claude settings
+ */
+export function isDamperMcpConfigured() {
+    if (!fs.existsSync(CLAUDE_SETTINGS_FILE)) {
+        return false;
+    }
+    try {
+        const settings = JSON.parse(fs.readFileSync(CLAUDE_SETTINGS_FILE, 'utf-8'));
+        return !!settings.mcpServers?.damper;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Get the current API key from MCP config or environment
+ */
+export function getConfiguredApiKey() {
+    // First check environment
+    if (process.env.DAMPER_API_KEY) {
+        return process.env.DAMPER_API_KEY;
+    }
+    // Then check Claude settings
+    if (!fs.existsSync(CLAUDE_SETTINGS_FILE)) {
+        return undefined;
+    }
+    try {
+        const settings = JSON.parse(fs.readFileSync(CLAUDE_SETTINGS_FILE, 'utf-8'));
+        return settings.mcpServers?.damper?.env?.DAMPER_API_KEY;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Get the recommended MCP configuration
+ */
+export function getDamperMcpConfig(apiKey) {
+    const config = {
+        command: 'npx',
+        args: ['-y', '@damper/mcp'],
+    };
+    if (apiKey) {
+        config.env = { DAMPER_API_KEY: apiKey };
+    }
+    return config;
+}
+/**
+ * Configure Damper MCP in Claude settings
+ */
+export function configureDamperMcp(apiKey) {
+    // Ensure directory exists
+    if (!fs.existsSync(CLAUDE_SETTINGS_DIR)) {
+        fs.mkdirSync(CLAUDE_SETTINGS_DIR, { recursive: true });
+    }
+    // Load existing settings or create new
+    let settings = {};
+    if (fs.existsSync(CLAUDE_SETTINGS_FILE)) {
+        try {
+            settings = JSON.parse(fs.readFileSync(CLAUDE_SETTINGS_FILE, 'utf-8'));
+        }
+        catch {
+            // Start fresh if corrupted
+            settings = {};
+        }
+    }
+    // Add/update MCP config
+    if (!settings.mcpServers) {
+        settings.mcpServers = {};
+    }
+    settings.mcpServers.damper = getDamperMcpConfig(apiKey);
+    // Write back
+    fs.writeFileSync(CLAUDE_SETTINGS_FILE, JSON.stringify(settings, null, 2));
+}
+/**
+ * Interactive setup for Damper MCP
+ * Returns the API key (either existing or newly entered)
+ */
+export async function setupDamperMcp() {
+    console.log(pc.yellow('\nDamper MCP is not configured in Claude Code.'));
+    console.log(pc.dim('The MCP server allows Claude to interact with your Damper tasks.\n'));
+    const shouldSetup = await confirm({
+        message: 'Would you like to set it up now?',
+        default: true,
+    });
+    if (!shouldSetup) {
+        console.log(pc.dim('\nYou can set it up later by running:'));
+        console.log(pc.cyan('  claude mcp add damper npx @damper/mcp\n'));
+        return null;
+    }
+    // Check if we already have an API key in the environment
+    const existingKey = process.env.DAMPER_API_KEY;
+    let apiKey;
+    if (existingKey) {
+        console.log(pc.dim('\nFound DAMPER_API_KEY in environment.'));
+        const useExisting = await confirm({
+            message: 'Use the API key from your environment?',
+            default: true,
+        });
+        if (useExisting) {
+            apiKey = existingKey;
+        }
+        else {
+            apiKey = await promptForApiKey();
+        }
+    }
+    else {
+        apiKey = await promptForApiKey();
+    }
+    // Configure MCP
+    console.log(pc.dim('\nConfiguring Damper MCP...'));
+    configureDamperMcp(apiKey);
+    console.log(pc.green('✓ Damper MCP configured in ~/.claude/settings.json'));
+    // Set in environment for current session
+    process.env.DAMPER_API_KEY = apiKey;
+    return apiKey;
+}
+async function promptForApiKey() {
+    console.log(pc.dim('\nGet your API key from: https://usedamper.com → Settings → API Keys\n'));
+    const apiKey = await password({
+        message: 'Enter your Damper API key:',
+        mask: '*',
+        validate: (value) => {
+            if (!value || value.trim().length === 0) {
+                return 'API key is required';
+            }
+            if (value.length < 10) {
+                return 'API key seems too short';
+            }
+            return true;
+        },
+    });
+    return apiKey.trim();
+}
+/**
+ * Ensure MCP is configured, offering to set it up if not
+ * Returns the API key to use
+ */
+export async function ensureMcpConfigured() {
+    // Check if already configured
+    if (isDamperMcpConfigured()) {
+        const apiKey = getConfiguredApiKey();
+        if (apiKey) {
+            return apiKey;
+        }
+        // MCP configured but no API key - need to add it
+        console.log(pc.yellow('\nDamper MCP is configured but no API key found.'));
+        const key = await promptForApiKey();
+        configureDamperMcp(key);
+        process.env.DAMPER_API_KEY = key;
+        return key;
+    }
+    // Not configured - run setup
+    const apiKey = await setupDamperMcp();
+    if (!apiKey) {
+        // User declined setup
+        console.log(pc.red('\nCannot continue without Damper MCP configuration.'));
+        process.exit(1);
+    }
+    return apiKey;
+}
+/**
+ * Launch Claude Code in a directory
+ */
+export async function launchClaude(options) {
+    const { cwd, taskId, taskTitle } = options;
+    console.log(pc.green(`\nStarting Claude Code for task #${taskId}: ${taskTitle}`));
+    console.log(pc.dim(`Directory: ${cwd}\n`));
+    // Build initial prompt
+    const initialPrompt = [
+        `I'm working on task #${taskId}: ${taskTitle}`,
+        '',
+        'Please read TASK_CONTEXT.md for full context, critical rules, and the implementation plan.',
+        '',
+        'Remember to:',
+        '1. Use `add_commit` after each git commit',
+        '2. Use `add_note` for important decisions',
+        '3. Call `complete_task` when done or `abandon_task` if stopping early',
+    ].join('\n');
+    // Launch Claude Code
+    // Using subprocess with inherited stdio so user can interact
+    try {
+        await execa('claude', ['--print', initialPrompt], {
+            cwd,
+            stdio: 'inherit',
+            env: {
+                ...process.env,
+            },
+        });
+    }
+    catch (err) {
+        const error = err;
+        if (error.code === 'ENOENT') {
+            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);
+        }
+        throw err;
+    }
+}
+/**
+ * Check if Claude Code CLI is installed
+ */
+export async function isClaudeInstalled() {
+    try {
+        await execa('claude', ['--version'], { stdio: 'pipe' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/services/context-bootstrap.d.ts

@@ -0,0 +1,18 @@
+import type { DamperApi } from './damper-api.js';
+export interface BootstrapOptions {
+    api: DamperApi;
+    taskId: string;
+    worktreePath: string;
+}
+export interface BootstrapResult {
+    taskContextPath: string;
+    claudeMdUpdated: boolean;
+}
+/**
+ * Fetch all relevant context from Damper and write local files
+ */
+export declare function bootstrapContext(options: BootstrapOptions): Promise<BootstrapResult>;
+/**
+ * Refresh TASK_CONTEXT.md with latest data from Damper (for resume scenarios)
+ */
+export declare function refreshContext(options: BootstrapOptions): Promise<BootstrapResult>;

package/dist/services/context-bootstrap.js

@@ -0,0 +1,94 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import pc from 'picocolors';
+import { generateTaskContext } from '../templates/TASK_CONTEXT.md.js';
+import { generateClaudeAppend } from '../templates/CLAUDE_APPEND.md.js';
+const TASK_CONTEXT_FILE = 'TASK_CONTEXT.md';
+const CLAUDE_MD_FILE = 'CLAUDE.md';
+const TASK_SECTION_MARKER = '## Current Task:';
+/**
+ * Fetch all relevant context from Damper and write local files
+ */
+export async function bootstrapContext(options) {
+    const { api, taskId, worktreePath } = options;
+    console.log(pc.dim('Fetching task details...'));
+    const task = await api.getTask(taskId);
+    console.log(pc.dim('Fetching project context...'));
+    const context = await api.getProjectContext(taskId);
+    // Fetch full content of relevant sections
+    const sections = [];
+    const relevantSections = context.relevantSections || [];
+    if (relevantSections.length > 0) {
+        console.log(pc.dim(`Fetching ${relevantSections.length} relevant context sections...`));
+        for (const sectionName of relevantSections) {
+            try {
+                const result = await api.getContextSection(sectionName);
+                // Handle both single section and glob pattern responses
+                if ('pattern' in result && result.sections) {
+                    sections.push(...result.sections);
+                }
+                else if ('section' in result && 'content' in result) {
+                    sections.push(result);
+                }
+            }
+            catch (err) {
+                console.log(pc.dim(`  Could not fetch section: ${sectionName}`));
+            }
+        }
+    }
+    // Fetch templates
+    console.log(pc.dim('Fetching templates...'));
+    const templatesResult = await api.listTemplates();
+    const templates = templatesResult.isEmpty ? [] : templatesResult.templates;
+    // Fetch modules
+    console.log(pc.dim('Fetching modules...'));
+    const modulesResult = await api.listModules();
+    const modules = modulesResult.isEmpty ? [] : modulesResult.modules;
+    // Get agent instructions
+    console.log(pc.dim('Fetching Damper workflow instructions...'));
+    const instructions = await api.getAgentInstructions('section');
+    // Generate TASK_CONTEXT.md
+    const taskContext = generateTaskContext({
+        task,
+        criticalRules: context.criticalRules || [],
+        sections,
+        templates,
+        modules,
+        damperInstructions: instructions.content,
+    });
+    // Write TASK_CONTEXT.md
+    const taskContextPath = path.join(worktreePath, TASK_CONTEXT_FILE);
+    console.log(pc.dim(`Writing ${TASK_CONTEXT_FILE}...`));
+    await fs.promises.writeFile(taskContextPath, taskContext, 'utf-8');
+    // Update CLAUDE.md with task section
+    const claudeMdPath = path.join(worktreePath, CLAUDE_MD_FILE);
+    let claudeMdUpdated = false;
+    if (fs.existsSync(claudeMdPath)) {
+        console.log(pc.dim(`Updating ${CLAUDE_MD_FILE}...`));
+        let claudeMd = await fs.promises.readFile(claudeMdPath, 'utf-8');
+        // Remove any existing task section
+        const markerIndex = claudeMd.indexOf(TASK_SECTION_MARKER);
+        if (markerIndex !== -1) {
+            claudeMd = claudeMd.slice(0, markerIndex).trimEnd();
+        }
+        // Append new task section
+        const taskSection = generateClaudeAppend({
+            taskId,
+            taskTitle: task.title,
+        });
+        claudeMd = `${claudeMd}\n\n${taskSection}\n`;
+        await fs.promises.writeFile(claudeMdPath, claudeMd, 'utf-8');
+        claudeMdUpdated = true;
+    }
+    return {
+        taskContextPath,
+        claudeMdUpdated,
+    };
+}
+/**
+ * Refresh TASK_CONTEXT.md with latest data from Damper (for resume scenarios)
+ */
+export async function refreshContext(options) {
+    // For now, just run bootstrap again - it will overwrite with fresh data
+    return bootstrapContext(options);
+}

package/dist/services/damper-api.d.ts

@@ -0,0 +1,154 @@
+export interface Task {
+    id: string;
+    title: string;
+    type: string;
+    status: string;
+    priority: string;
+    effort?: string | null;
+    quarter?: string | null;
+    labels?: string[];
+    dueDate?: string | null;
+    feedbackCount: number;
+    hasImplementationPlan: boolean;
+    subtaskProgress?: {
+        done: number;
+        total: number;
+    } | null;
+}
+export interface TaskDetail extends Task {
+    description?: string | null;
+    implementationPlan?: string | null;
+    voteScore: number;
+    subtasks?: Array<{
+        id: string;
+        title: string;
+        done: boolean;
+    }>;
+    agentNotes?: string | null;
+    commits?: Array<{
+        hash: string;
+        message: string;
+    }>;
+    feedback: Array<{
+        id: string;
+        title: string;
+        description: string;
+        voterCount: number;
+    }>;
+    lockedBy?: string | null;
+    lockedAt?: string | null;
+}
+export interface ContextSection {
+    section: string;
+    content: string;
+    updatedAt: string;
+    source: string;
+    tags?: string[];
+    appliesTo?: string[];
+}
+export interface ContextIndex {
+    isEmpty: boolean;
+    index: Array<{
+        section: string;
+        preview: string;
+        updatedAt: string;
+        tags?: string[];
+        appliesTo?: string[];
+    }>;
+    relevantSections?: string[];
+    hint?: string;
+    criticalRules?: string[];
+}
+export interface Template {
+    name: string;
+    description?: string | null;
+    content: string;
+    filePattern?: string | null;
+    tags?: string[];
+    updatedAt: string;
+}
+export interface Module {
+    name: string;
+    path: string;
+    port?: number | null;
+    dependsOn?: string[];
+    description?: string | null;
+    tags?: string[];
+    updatedAt: string;
+}
+export interface AgentInstructions {
+    format: 'markdown' | 'section';
+    content: string;
+    lastModified: string;
+}
+export interface StartTaskResult {
+    id: string;
+    status: string;
+    message: string;
+    context?: ContextIndex;
+}
+export interface LockConflictError extends Error {
+    lockInfo: {
+        error: string;
+        lockedBy: string;
+        lockedAt: string;
+    };
+}
+export declare class DamperApi {
+    private apiKey;
+    constructor(apiKey: string);
+    private request;
+    listTasks(filters?: {
+        status?: 'planned' | 'in_progress' | 'done' | 'all';
+        type?: 'bug' | 'feature' | 'improvement' | 'task';
+        quarter?: string;
+        sort?: 'importance' | 'newest' | 'votes';
+        limit?: number;
+    }): Promise<{
+        project: string;
+        tasks: Task[];
+    }>;
+    getTask(taskId: string): Promise<TaskDetail>;
+    startTask(taskId: string, force?: boolean): Promise<StartTaskResult>;
+    getProjectContext(taskId?: string): Promise<ContextIndex>;
+    getContextSection(section: string): Promise<ContextSection | {
+        pattern: string;
+        sections: ContextSection[];
+    }>;
+    listContextSections(): Promise<{
+        sections: Array<{
+            section: string;
+            updatedAt: string;
+            source: string;
+            preview: string;
+            tags?: string[];
+            appliesTo?: string[];
+        }>;
+        isEmpty: boolean;
+    }>;
+    listTemplates(): Promise<{
+        templates: Array<{
+            name: string;
+            description?: string | null;
+            filePattern?: string | null;
+            tags?: string[];
+            preview: string;
+            updatedAt: string;
+        }>;
+        isEmpty: boolean;
+    }>;
+    getTemplate(name: string): Promise<Template>;
+    listModules(): Promise<{
+        modules: Module[];
+        isEmpty: boolean;
+    }>;
+    getModule(name: string): Promise<Module>;
+    getAgentInstructions(format?: 'markdown' | 'section'): Promise<AgentInstructions>;
+    getLinkedFeedback(taskId: string): Promise<Array<{
+        id: string;
+        title: string;
+        description: string;
+        voterCount: number;
+    }>>;
+}
+export declare function createDamperApi(apiKey?: string): DamperApi;

package/dist/services/damper-api.js

@@ -0,0 +1,151 @@
+// Config
+const API_URL = process.env.DAMPER_API_URL || 'https://api.usedamper.com';
+// API Client class
+export class DamperApi {
+    apiKey;
+    constructor(apiKey) {
+        this.apiKey = apiKey;
+    }
+    async request(method, path, body) {
+        const res = await fetch(`${API_URL}${path}`, {
+            method,
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        if (!res.ok) {
+            const err = await res.json().catch(() => ({}));
+            // Preserve lock info for 409 conflicts
+            if (res.status === 409 && err.lockedBy) {
+                const lockErr = new Error(err.error || `HTTP ${res.status}`);
+                lockErr.lockInfo = err;
+                throw lockErr;
+            }
+            throw new Error(err.error || `HTTP ${res.status}`);
+        }
+        return res.json();
+    }
+    // Tasks
+    async listTasks(filters) {
+        const params = new URLSearchParams();
+        if (filters?.status)
+            params.set('status', filters.status);
+        if (filters?.type)
+            params.set('type', filters.type);
+        if (filters?.quarter)
+            params.set('quarter', filters.quarter);
+        if (filters?.sort)
+            params.set('sort', filters.sort);
+        if (filters?.limit)
+            params.set('limit', String(filters.limit));
+        const query = params.toString();
+        const data = await this.request('GET', `/api/agent/tasks${query ? `?${query}` : ''}`);
+        return { project: data.project.name, tasks: data.tasks };
+    }
+    async getTask(taskId) {
+        return this.request('GET', `/api/agent/tasks/${taskId}`);
+    }
+    async startTask(taskId, force) {
+        return this.request('POST', `/api/agent/tasks/${taskId}/start`, force ? { force: true } : undefined);
+    }
+    // Project Context
+    async getProjectContext(taskId) {
+        const params = taskId ? `?task_id=${taskId}` : '';
+        return this.request('GET', `/api/agent/context/index${params}`);
+    }
+    async getContextSection(section) {
+        // Encode each path segment individually but preserve slashes
+        const encodedSection = section
+            .split('/')
+            .map(part => encodeURIComponent(part).replace(/\*/g, '%2A'))
+            .join('/');
+        return this.request('GET', `/api/agent/context/${encodedSection}`);
+    }
+    async listContextSections() {
+        return this.request('GET', '/api/agent/context');
+    }
+    // Templates
+    async listTemplates() {
+        return this.request('GET', '/api/agent/templates');
+    }
+    async getTemplate(name) {
+        return this.request('GET', `/api/agent/templates/${name}`);
+    }
+    // Modules
+    async listModules() {
+        return this.request('GET', '/api/agent/modules');
+    }
+    async getModule(name) {
+        return this.request('GET', `/api/agent/modules/${name}`);
+    }
+    // Agent Instructions
+    async getAgentInstructions(format = 'section') {
+        // The MCP server has this hardcoded, so we'll return the same content
+        const lastModified = '2025-02-05';
+        const section = `## Task Management with Damper MCP
+
+> Last updated: ${lastModified}
+
+This project uses Damper MCP for task tracking. **You MUST follow this workflow.**
+
+### At Session Start (MANDATORY)
+1. \`get_project_context\` - **READ THIS FIRST.** Contains architecture, conventions, and critical project info.
+2. \`get_context_section\` - Fetch full content for sections relevant to your task
+3. \`list_tasks\` - Check for existing tasks to work on
+4. If working on a task: \`start_task\` to lock it
+
+### While Working
+- \`add_commit\` after each commit with hash and message
+- \`add_note\` for decisions: "Decision: chose X because Y"
+- \`update_subtask\` to mark subtask progress
+- **Follow patterns from project context** - Don't reinvent; use existing conventions
+
+### Feedback & Changelog Integration
+- \`link_feedback_to_task\` - Link user feedback IDs to your task (helps track what customer requests led to the feature)
+- When completing a **public** task, it auto-adds to the project's draft changelog
+- \`list_changelogs\` - View existing changelogs and drafts
+- \`create_changelog\` / \`update_changelog\` - Create or edit changelog entries (use \`summary\` for social-friendly posts)
+- \`add_to_changelog\` - Manually add completed tasks to a changelog
+- \`publish_changelog\` - Publish with optional email notifications and Twitter posting
+
+### At Session End (MANDATORY)
+- ALWAYS call \`add_note\` with session summary before stopping
+- ALWAYS call \`complete_task\` (if done) or \`abandon_task\` (if stopping early)
+- NEVER leave a started task without completing or abandoning it
+- If you learned something about the codebase, consider updating project context
+
+### Why This Matters
+- **Project context prevents mistakes** - Contains architecture decisions, gotchas, and patterns
+- Locked tasks block other agents from working on them
+- Commits and notes help the next agent continue the work
+- Updating context saves future agents from re-analyzing the codebase
+- Linking feedback connects customer requests to shipped features`;
+        if (format === 'markdown') {
+            return {
+                format: 'markdown',
+                content: `# CLAUDE.md\n\n${section}`,
+                lastModified,
+            };
+        }
+        return {
+            format: 'section',
+            content: section,
+            lastModified,
+        };
+    }
+    // Feedback
+    async getLinkedFeedback(taskId) {
+        const task = await this.getTask(taskId);
+        return task.feedback || [];
+    }
+}
+// Factory function for creating API client
+export function createDamperApi(apiKey) {
+    const key = apiKey || process.env.DAMPER_API_KEY;
+    if (!key) {
+        throw new Error('DAMPER_API_KEY required. Get one from Damper → Settings → API Keys');
+    }
+    return new DamperApi(key);
+}

package/dist/services/state.d.ts

@@ -0,0 +1,15 @@
+export interface WorktreeState {
+    taskId: string;
+    path: string;
+    branch: string;
+    projectRoot: string;
+    createdAt: string;
+}
+export declare function getWorktrees(): WorktreeState[];
+export declare function getWorktreeByTaskId(taskId: string): WorktreeState | undefined;
+export declare function getWorktreeByPath(worktreePath: string): WorktreeState | undefined;
+export declare function addWorktree(worktree: WorktreeState): void;
+export declare function removeWorktree(taskId: string): void;
+export declare function removeWorktreeByPath(worktreePath: string): void;
+export declare function cleanupStaleWorktrees(): WorktreeState[];
+export declare function getWorktreesForProject(projectRoot: string): WorktreeState[];