cairn-work 0.2.0

package/lib/agents/detect.test.js

@@ -0,0 +1,108 @@
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
+import { detectAgents, getAgentName, isSupportedAgent } from './detect.js';
+import { existsSync, mkdirSync, rmSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+describe('Agent Detection', () => {
+  let originalEnv;
+  let testHome;
+  
+  beforeEach(() => {
+    // Save original environment
+    originalEnv = { ...process.env };
+    
+    // Create temporary home directory for testing
+    testHome = join(tmpdir(), `cairn-test-${Date.now()}`);
+    mkdirSync(testHome, { recursive: true });
+  });
+  
+  afterEach(() => {
+    // Restore environment
+    process.env = originalEnv;
+    
+    // Clean up test directory
+    if (existsSync(testHome)) {
+      rmSync(testHome, { recursive: true, force: true });
+    }
+  });
+  
+  test('detectAgents returns generic when no agents found', () => {
+    // Clear environment variables that might detect agents
+    delete process.env.ANTHROPIC_API_KEY;
+    delete process.env.CLAUDE_CODE_WORKSPACE;
+    delete process.env.CURSOR_WORKSPACE;
+    delete process.env.WINDSURF_WORKSPACE;
+    
+    const result = detectAgents();
+    
+    expect(result).toHaveProperty('primary');
+    expect(result).toHaveProperty('detected');
+    expect(Array.isArray(result.detected)).toBe(true);
+    
+    // If running in environment with actual agents installed, primary might not be generic
+    // Just verify it returns a valid agent type
+    expect(isSupportedAgent(result.primary)).toBe(true);
+  });
+  
+  test('detectAgents finds Clawdbot when .clawdbot exists', () => {
+    // This test only runs if .clawdbot actually exists
+    const clawdbotPath = join(process.env.HOME, '.clawdbot');
+    if (existsSync(clawdbotPath)) {
+      const result = detectAgents();
+      expect(result.detected).toContain('clawdbot');
+    }
+  });
+  
+  test('detectAgents finds Claude Code when env var set', () => {
+    process.env.ANTHROPIC_API_KEY = 'test-key';
+    
+    const result = detectAgents();
+    
+    expect(result.detected).toContain('claude-code');
+  });
+  
+  test('detectAgents finds Cursor when .cursorrules exists', () => {
+    // Only test if in actual Cursor environment
+    if (existsSync('.cursorrules')) {
+      const result = detectAgents();
+      expect(result.detected).toContain('cursor');
+    }
+  });
+  
+  test('detectAgents handles multiple agents', () => {
+    process.env.ANTHROPIC_API_KEY = 'test-key';
+    process.env.CURSOR_WORKSPACE = 'test-workspace';
+    
+    const result = detectAgents();
+    
+    expect(result.detected.length).toBeGreaterThanOrEqual(1);
+    expect(result.primary).toBeTruthy();
+  });
+  
+  test('getAgentName returns correct display names', () => {
+    expect(getAgentName('clawdbot')).toBe('Clawdbot');
+    expect(getAgentName('claude-code')).toBe('Claude Code');
+    expect(getAgentName('cursor')).toBe('Cursor');
+    expect(getAgentName('windsurf')).toBe('Windsurf');
+    expect(getAgentName('generic')).toBe('Generic AI Agent');
+  });
+  
+  test('getAgentName returns input for unknown agent', () => {
+    expect(getAgentName('unknown-agent')).toBe('unknown-agent');
+  });
+  
+  test('isSupportedAgent validates known agents', () => {
+    expect(isSupportedAgent('clawdbot')).toBe(true);
+    expect(isSupportedAgent('claude-code')).toBe(true);
+    expect(isSupportedAgent('cursor')).toBe(true);
+    expect(isSupportedAgent('windsurf')).toBe(true);
+    expect(isSupportedAgent('generic')).toBe(true);
+  });
+  
+  test('isSupportedAgent rejects unknown agents', () => {
+    expect(isSupportedAgent('unknown')).toBe(false);
+    expect(isSupportedAgent('invalid')).toBe(false);
+    expect(isSupportedAgent('')).toBe(false);
+  });
+});

package/lib/agents/generic.js

@@ -0,0 +1,60 @@
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import chalk from 'chalk';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Generic agent setup - just provide instructions
+ */
+export async function setupGeneric(workspacePath) {
+  // For generic agents, we can't auto-configure
+  // Just provide clear instructions
+  console.log(chalk.yellow('ℹ'), 'Generic agent detected - manual setup required');
+  return true;
+}
+
+/**
+ * Get setup instructions for generic agents
+ */
+export function getGenericInstructions(workspacePath) {
+  const skillPath = join(dirname(__dirname), '../skills/agent-skill.template.md');
+  
+  let output = '\n';
+  output += chalk.bold('Manual Setup Required') + '\n\n';
+  output += 'Your Cairn workspace: ' + chalk.cyan(workspacePath) + '\n\n';
+  output += chalk.bold('To configure your AI agent:') + '\n\n';
+  output += '1. Share this with your agent:\n';
+  output += '   ' + chalk.dim('─────────────────────────────────────') + '\n';
+  output += '   ' + chalk.yellow('I\'m using Cairn for project management.') + '\n';
+  output += '   ' + chalk.yellow('My workspace is at: ' + workspacePath) + '\n';
+  output += '   ' + chalk.yellow('Please read the agent skill documentation at:') + '\n';
+  output += '   ' + chalk.yellow(skillPath) + '\n';
+  output += '   ' + chalk.dim('─────────────────────────────────────') + '\n\n';
+  output += '2. ' + chalk.bold('Or copy the skill to your agent\'s context:') + '\n';
+  output += '   - For AI coding assistants: Add ' + chalk.cyan(skillPath) + ' to your workspace\n';
+  output += '   - For chat agents: Share the skill content in your first message\n\n';
+  output += '3. ' + chalk.bold('Test it:') + '\n';
+  output += '   Ask your agent:\n';
+  output += '     ' + chalk.yellow('"Help me create a project called Launch My App"') + '\n\n';
+  output += chalk.bold('Supported agents with auto-setup:') + '\n';
+  output += '- Clawdbot (detected via ~/.clawdbot/)\n';
+  output += '- Claude Code (workspace-based)\n';
+  output += '- Cursor (uses .cursorrules)\n';
+  output += '- Windsurf (workspace-based)\n\n';
+  output += chalk.dim('If you install one of these agents later, run:') + '\n';
+  output += chalk.dim('  cairn onboard --force') + '\n';
+  
+  return output;
+}
+
+/**
+ * Verify generic setup (always returns guidance)
+ */
+export function verifyGeneric() {
+  return {
+    success: true,
+    message: 'Manual setup - verify agent can read workspace'
+  };
+}

package/lib/commands/create.js

@@ -0,0 +1,158 @@
+import { existsSync, mkdirSync, writeFileSync, readdirSync } from 'fs';
+import { join } from 'path';
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import { resolveWorkspace } from '../setup/workspace.js';
+
+function slugify(text) {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+function getToday() {
+  return new Date().toISOString().split('T')[0];
+}
+
+function getDueDate(daysFromNow = 7) {
+  const date = new Date();
+  date.setDate(date.getDate() + daysFromNow);
+  return date.toISOString().split('T')[0];
+}
+
+export default async function create(type, name, options) {
+  const workspacePath = resolveWorkspace();
+
+  if (!workspacePath) {
+    console.error(chalk.red('Error:'), 'No workspace found. Run:', chalk.cyan('cairn init'));
+    process.exit(1);
+  }
+  
+  const slug = slugify(name);
+  
+  switch (type) {
+    case 'project':
+      await createProject(workspacePath, name, slug, options);
+      break;
+    case 'task':
+      await createTask(workspacePath, name, slug, options);
+      break;
+    default:
+      console.error(chalk.red('Error:'), `Unknown type: ${type}`);
+      console.log(chalk.dim('Valid types: project, task'));
+      process.exit(1);
+  }
+}
+
+async function createProject(workspacePath, name, slug, options) {
+  const projectPath = join(workspacePath, 'projects', slug);
+  
+  if (existsSync(projectPath)) {
+    console.error(chalk.red('Error:'), `Project already exists: ${slug}`);
+    process.exit(1);
+  }
+  
+  // Create folders
+  mkdirSync(projectPath, { recursive: true });
+  mkdirSync(join(projectPath, 'tasks'), { recursive: true });
+  
+  // Create charter.md
+  const charterPath = join(projectPath, 'charter.md');
+  const charter = `---
+title: ${name}
+description: ${options.description || name}
+status: active
+priority: 2
+created: ${getToday()}
+due: ${options.due || getDueDate(30)}
+owner: ${options.assignee || 'me'}
+default_autonomy: draft
+budget: 100
+spent: 0
+---
+
+## Why This Matters
+
+${options.objective || '[Describe why this project is important]'}
+
+## Success Criteria
+
+- [ ] [Define what success looks like]
+- [ ] [Add measurable outcomes]
+- [ ] [Specify completion criteria]
+
+## Context
+
+[Add relevant background, constraints, or dependencies]
+
+## Work Log
+
+### ${getToday()} - Created
+Project created via Cairn CLI.
+`;
+  
+  writeFileSync(charterPath, charter);
+  
+  console.log(chalk.green('✓'), `Project created: ${chalk.cyan(slug)}`);
+  console.log(chalk.dim(`  Location: ${projectPath}`));
+  console.log(chalk.dim(`  Charter: ${charterPath}`));
+  console.log();
+  console.log(chalk.dim('Next:'), `cairn create task "Task Name" --project ${slug}`);
+}
+
+async function createTask(workspacePath, name, slug, options) {
+  const projectSlug = options.project;
+  
+  if (!projectSlug) {
+    console.error(chalk.red('Error:'), 'Missing --project flag');
+    console.log(chalk.dim('Example:'), chalk.cyan(`cairn create task "${name}" --project my-project`));
+    process.exit(1);
+  }
+  
+  const projectPath = join(workspacePath, 'projects', projectSlug);
+  if (!existsSync(projectPath)) {
+    console.error(chalk.red('Error:'), `Project not found: ${projectSlug}`);
+    process.exit(1);
+  }
+  
+  const tasksDir = join(projectPath, 'tasks');
+  if (!existsSync(tasksDir)) {
+    mkdirSync(tasksDir, { recursive: true });
+  }
+  
+  const taskPath = join(tasksDir, `${slug}.md`);
+  
+  if (existsSync(taskPath)) {
+    console.error(chalk.red('Error:'), `Task already exists: ${slug}`);
+    process.exit(1);
+  }
+  
+  // Create task file
+  const task = `---
+title: ${name}
+description: ${options.description || name}
+assignee: ${options.assignee || 'you'}
+status: ${options.status || 'pending'}
+created: ${getToday()}
+due: ${options.due || getDueDate(7)}
+autonomy: draft
+spend: 0
+artifacts: []
+---
+
+## Objective
+
+${options.objective || '[Describe what needs to be accomplished]'}
+
+## Work Log
+
+### ${getToday()} - Created
+Task created via Cairn CLI.
+`;
+  
+  writeFileSync(taskPath, task);
+  
+  console.log(chalk.green('✓'), `Task created: ${chalk.cyan(slug)}`);
+  console.log(chalk.dim(`  Location: ${taskPath}`));
+}

package/lib/commands/doctor.js

@@ -0,0 +1,137 @@
+import { existsSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+
+import chalk from 'chalk';
+import ora from 'ora';
+
+import { detectAgents, getAgentName } from '../agents/detect.js';
+import { verifyClawdbot } from '../agents/clawdbot.js';
+import { verifyClaudeCode } from '../agents/claude-code.js';
+import { verifyCursor } from '../agents/cursor.js';
+import { validateWorkspace, createWorkspace, createWelcomeFile, resolveWorkspace } from '../setup/workspace.js';
+
+export default async function doctor() {
+  console.log(chalk.bold.cyan('\n🏔️  Cairn Doctor\n'));
+  console.log(chalk.dim('Checking workspace health...\n'));
+
+  const workspacePath = resolveWorkspace() || join(homedir(), 'cairn');
+  let issues = [];
+  let warnings = [];
+  
+  // Check 1: Workspace exists
+  const spinner = ora('Checking workspace').start();
+  if (!existsSync(workspacePath)) {
+    spinner.fail('Workspace not found');
+    issues.push({
+      problem: `Workspace not found at ${workspacePath}`,
+      fix: 'Run: cairn init'
+    });
+  } else {
+    const { valid, missing } = validateWorkspace(workspacePath);
+    if (!valid) {
+      spinner.warn('Workspace incomplete');
+      warnings.push({
+        problem: `Missing folders: ${missing.join(', ')}`,
+        fix: 'Run: cairn init --path ' + workspacePath
+      });
+    } else {
+      spinner.succeed('Workspace structure valid');
+    }
+  }
+  
+  // Check 2: Agent configuration
+  const agentSpinner = ora('Checking agent configuration').start();
+  const { primary, detected } = detectAgents();
+  
+  if (detected.length === 0) {
+    agentSpinner.info('No specific agent detected');
+    warnings.push({
+      problem: 'No AI agent auto-detected',
+      fix: 'Run: cairn onboard --agent <type>'
+    });
+  } else {
+    agentSpinner.succeed(`Detected: ${detected.map(getAgentName).join(', ')}`);
+    
+    // Verify each detected agent
+    for (const agent of detected) {
+      const verifySpinner = ora(`Verifying ${getAgentName(agent)}`).start();
+      let result;
+      
+      switch (agent) {
+        case 'clawdbot':
+          result = verifyClawdbot();
+          break;
+        case 'claude-code':
+          result = verifyClaudeCode();
+          break;
+        case 'cursor':
+          result = verifyCursor();
+          break;
+        default:
+          result = { success: true, message: 'No verification available' };
+      }
+      
+      if (result.success) {
+        verifySpinner.succeed(result.message);
+      } else {
+        verifySpinner.fail(result.message);
+        issues.push({
+          problem: `${getAgentName(agent)}: ${result.message}`,
+          fix: `Run: cairn onboard --agent ${agent} --force`
+        });
+      }
+    }
+  }
+  
+  // Check 3: README exists
+  const readmeSpinner = ora('Checking README').start();
+  const readmePath = join(workspacePath, 'README.md');
+  if (existsSync(readmePath)) {
+    readmeSpinner.succeed('README exists');
+  } else {
+    readmeSpinner.warn('README missing');
+    warnings.push({
+      problem: 'Welcome README not found',
+      fix: 'Will be created automatically'
+    });
+    if (existsSync(workspacePath)) {
+      createWelcomeFile(workspacePath);
+      console.log(chalk.green('✓'), 'README created');
+    }
+  }
+  
+  // Summary
+  console.log();
+  console.log(chalk.bold('Summary:\n'));
+  
+  if (issues.length === 0 && warnings.length === 0) {
+    console.log(chalk.green('✓'), chalk.bold('Everything looks good!'));
+    console.log();
+    console.log(chalk.dim('Your Cairn workspace is healthy.'));
+    console.log(chalk.dim('Location:'), chalk.cyan(workspacePath));
+    console.log();
+    return;
+  }
+  
+  if (issues.length > 0) {
+    console.log(chalk.red.bold(`${issues.length} issue(s) found:\n`));
+    for (const issue of issues) {
+      console.log(chalk.red('✗'), issue.problem);
+      console.log(chalk.dim('  Fix:'), chalk.cyan(issue.fix));
+      console.log();
+    }
+  }
+  
+  if (warnings.length > 0) {
+    console.log(chalk.yellow.bold(`${warnings.length} warning(s):\n`));
+    for (const warning of warnings) {
+      console.log(chalk.yellow('⚠'), warning.problem);
+      console.log(chalk.dim('  Fix:'), chalk.cyan(warning.fix));
+      console.log();
+    }
+  }
+  
+  console.log(chalk.dim('Run'), chalk.cyan('cairn --help'), chalk.dim('for more commands.'));
+  console.log();
+}

package/lib/commands/init.js

@@ -0,0 +1,28 @@
+import chalk from 'chalk';
+
+import { createWorkspace, createWelcomeFile, workspaceExists } from '../setup/workspace.js';
+
+export default async function init(options) {
+  console.log(chalk.bold.cyan('\n🏔️  Initializing Cairn\n'));
+  
+  const workspacePath = options.path || process.cwd();
+  
+  if (workspaceExists(workspacePath)) {
+    console.log(chalk.yellow('⚠'), `Workspace already exists at ${workspacePath}`);
+    console.log(chalk.dim('Use --path to specify a different location'));
+    return;
+  }
+  
+  // Create workspace
+  createWorkspace(workspacePath);
+  createWelcomeFile(workspacePath);
+  
+  console.log();
+  console.log(chalk.green('✓'), `Workspace created at ${chalk.cyan(workspacePath)}`);
+  console.log();
+  console.log(chalk.dim('Next steps:'));
+  console.log(chalk.dim('  • Create a project: cairn create project "My Project"'));
+  console.log(chalk.dim('  • Configure agent: cairn onboard'));
+  console.log(chalk.dim('  • Check health: cairn doctor'));
+  console.log();
+}

package/lib/commands/onboard.js

@@ -0,0 +1,141 @@
+import { homedir } from 'os';
+import { join } from 'path';
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import ora from 'ora';
+
+import { detectAgents, getAgentName } from '../agents/detect.js';
+import { setupClawdbot, getClawdbotInstructions } from '../agents/clawdbot.js';
+import { setupClaudeCode, getClaudeCodeInstructions } from '../agents/claude-code.js';
+import { setupCursor, getCursorInstructions } from '../agents/cursor.js';
+import { setupGeneric, getGenericInstructions } from '../agents/generic.js';
+import { createWorkspace, createWelcomeFile, workspaceExists } from '../setup/workspace.js';
+
+export default async function onboard(options) {
+  console.log(chalk.bold.cyan('\n🏔️  Cairn Onboarding\n'));
+  
+  // Prompt for workspace path (if not provided)
+  let workspacePath = options.path;
+  if (!workspacePath) {
+    const currentDir = process.cwd();
+    const cairnDir = join(homedir(), 'cairn');
+
+    const { location } = await inquirer.prompt([{
+      type: 'list',
+      name: 'location',
+      message: 'Where should Cairn store your project files?',
+      choices: [
+        { name: `Here (${currentDir})`, value: currentDir },
+        { name: `~/cairn`, value: cairnDir },
+        { name: 'Somewhere else...', value: '__custom__' }
+      ]
+    }]);
+
+    if (location === '__custom__') {
+      const { customPath } = await inquirer.prompt([{
+        type: 'input',
+        name: 'customPath',
+        message: 'Enter the full path:'
+      }]);
+      workspacePath = customPath;
+    } else {
+      workspacePath = location;
+    }
+  }
+  
+  // Check if already set up
+  if (workspaceExists(workspacePath) && !options.force) {
+    const { proceed } = await inquirer.prompt([{
+      type: 'confirm',
+      name: 'proceed',
+      message: `Workspace already exists at ${workspacePath}. Re-run onboarding?`,
+      default: false
+    }]);
+    
+    if (!proceed) {
+      console.log(chalk.yellow('\nOnboarding cancelled.'));
+      return;
+    }
+  }
+  
+  // Step 1: Detect agents
+  let agentType = options.agent;
+  
+  if (!agentType) {
+    const spinner = ora('Detecting AI agents').start();
+    const { primary, detected } = detectAgents();
+    spinner.stop();
+    
+    if (detected.length > 1) {
+      console.log(chalk.green('✓'), `Detected agents: ${detected.map(getAgentName).join(', ')}`);
+      
+      const { selected } = await inquirer.prompt([{
+        type: 'list',
+        name: 'selected',
+        message: 'Multiple agents detected. Which one do you want to configure?',
+        choices: detected.map(type => ({
+          name: getAgentName(type),
+          value: type
+        }))
+      }]);
+      
+      agentType = selected;
+    } else if (detected.length === 1) {
+      agentType = primary;
+      console.log(chalk.green('✓'), `Detected: ${getAgentName(agentType)}`);
+    } else {
+      agentType = 'generic';
+      console.log(chalk.yellow('ℹ'), 'No specific agent detected - using generic setup');
+    }
+  }
+  
+  // Step 2: Create workspace
+  console.log();
+  createWorkspace(workspacePath);
+  createWelcomeFile(workspacePath);
+  
+  // Step 3: Set up agent
+  console.log();
+  const setupSpinner = ora(`Configuring ${getAgentName(agentType)}`).start();
+  
+  try {
+    switch (agentType) {
+      case 'clawdbot':
+        await setupClawdbot(workspacePath);
+        setupSpinner.succeed(`${getAgentName(agentType)} configured`);
+        console.log(getClawdbotInstructions(workspacePath));
+        break;
+        
+      case 'claude-code':
+        await setupClaudeCode(workspacePath);
+        setupSpinner.succeed(`${getAgentName(agentType)} configured`);
+        console.log(getClaudeCodeInstructions(workspacePath));
+        break;
+        
+      case 'cursor':
+        await setupCursor(workspacePath);
+        setupSpinner.succeed(`${getAgentName(agentType)} configured`);
+        console.log(getCursorInstructions(workspacePath));
+        break;
+        
+      case 'generic':
+      default:
+        await setupGeneric(workspacePath);
+        setupSpinner.stop();
+        console.log(getGenericInstructions(workspacePath));
+        break;
+    }
+  } catch (error) {
+    setupSpinner.fail('Setup failed');
+    console.error(chalk.red('Error:'), error.message);
+    process.exit(1);
+  }
+  
+  // Success!
+  console.log(chalk.bold.green('\n🎉 Onboarding complete!\n'));
+  console.log(chalk.dim('Next steps:'));
+  console.log(chalk.dim('  1. Test your agent with: "Help me create a project"'));
+  console.log(chalk.dim('  2. Read the docs: cairn --help'));
+  console.log(chalk.dim('  3. Create your first project: cairn create project "My Project"'));
+  console.log();
+}