cairn-work 0.9.1 → 0.10.0

package/README.md

@@ -16,6 +16,27 @@ This creates a workspace and writes two context files your agent reads automatic
 
 No agent-specific configuration. Any AI agent that can read files is ready to go.
 
+## Quick Start
+
+```bash
+# See what you're working on
+cairn my
+
+# Start a task
+cairn start implement-auth
+
+# Add notes as you work
+cairn note implement-auth "Using passport.js for OAuth"
+
+# Mark it done
+cairn done implement-auth
+
+# Check workspace status
+cairn status
+```
+
+For complete command reference, see [COMMANDS.md](COMMANDS.md).
+
 ## How it works
 
 You and your AI agent share a folder of markdown files. Projects have charters. Tasks have objectives. Status fields track where everything stands — like a kanban board backed by text files.

package/bin/cairn.js

@@ -27,6 +27,18 @@ import doctor from '../lib/commands/doctor.js';
 import updateSkill from '../lib/commands/update-skill.js';
 import update from '../lib/commands/update.js';
 import upgrade from '../lib/commands/upgrade.js';
+import start from '../lib/commands/start.js';
+import done from '../lib/commands/done.js';
+import block from '../lib/commands/block.js';
+import unblock from '../lib/commands/unblock.js';
+import view from '../lib/commands/view.js';
+import active from '../lib/commands/active.js';
+import my from '../lib/commands/my.js';
+import artifact from '../lib/commands/artifact.js';
+import status from '../lib/commands/status.js';
+import note from '../lib/commands/note.js';
+import edit from '../lib/commands/edit.js';
+import search from '../lib/commands/search.js';
 
 // Onboard command - workspace setup with context files
 program
@@ -51,7 +63,8 @@ program
   .option('--project <slug>', 'Parent project (required for tasks)')
   .option('--assignee <name>', 'Assignee name', 'you')
   .option('--status <status>', 'Initial status', 'pending')
-  .option('--autonomy <level>', 'Autonomy level: propose, draft, or execute (tasks only)', 'draft')
+  .option('--priority <number>', 'Priority level (1=highest, default: 1)', '1')
+  .option('--autonomy <level>', 'Autonomy level: propose, draft, or execute (tasks only)', 'execute')
   .option('--due <date>', 'Due date (YYYY-MM-DD)')
   .option('--description <text>', 'Short description')
   .option('--objective <text>', 'Detailed objective')
@@ -110,6 +123,88 @@ program
   .description('Check for and install Cairn CLI updates')
   .action(upgrade);
 
+// Start command - mark task as in_progress
+program
+  .command('start <task-slug>')
+  .description('Start working on a task (sets status to in_progress)')
+  .option('--project <slug>', 'Project to search for the task')
+  .action(start);
+
+// Done command - mark task as complete (review or done based on autonomy)
+program
+  .command('done <task-slug>')
+  .description('Mark task as complete (review/done based on autonomy level)')
+  .option('--project <slug>', 'Project to search for the task')
+  .action(done);
+
+// Block command - mark task as blocked with reason
+program
+  .command('block <task-slug> <message>')
+  .description('Mark task as blocked with explanation')
+  .option('--project <slug>', 'Project to search for the task')
+  .action(block);
+
+// Unblock command - resume blocked task
+program
+  .command('unblock <task-slug> [message]')
+  .description('Unblock task and resume work (sets status to in_progress)')
+  .option('--project <slug>', 'Project to search for the task')
+  .action(unblock);
+
+// Note command - add quick note to task
+program
+  .command('note <task-slug> <message>')
+  .description('Add a quick note to task work log')
+  .option('--project <slug>', 'Project to search for the task')
+  .action(note);
+
+// View command - show full task details
+program
+  .command('view <task-slug>')
+  .description('View complete task details')
+  .option('--project <slug>', 'Project to search for the task')
+  .action(view);
+
+// Active command - show all in_progress tasks
+program
+  .command('active')
+  .description('Show all tasks currently in progress')
+  .action(active);
+
+// My command - show all my tasks grouped by status
+program
+  .command('my')
+  .description('Show all tasks assigned to me, grouped by status')
+  .action(my);
+
+// Artifact command - create Obsidian artifact and link to task
+program
+  .command('artifact <task-slug> <artifact-name>')
+  .description('Create an Obsidian artifact and link it to a task')
+  .option('--project <slug>', 'Project to search for the task')
+  .option('--open', 'Open the artifact in Obsidian after creation')
+  .action(artifact);
+
+// Status command - workspace overview
+program
+  .command('status')
+  .description('Show workspace overview with task counts by status')
+  .action(status);
+
+// Edit command - open task in editor
+program
+  .command('edit <task-slug>')
+  .description('Open task in $EDITOR')
+  .option('--project <slug>', 'Project to search for the task')
+  .action(edit);
+
+// Search command - find tasks by keyword
+program
+  .command('search <query>')
+  .description('Search tasks by keyword in title, description, or content')
+  .option('--project <slug>', 'Limit search to specific project')
+  .action(search);
+
 // Parse and handle errors
 program.parseAsync(process.argv).catch((error) => {
   console.error(chalk.red('Error:'), error.message);

package/lib/commands/active.js

@@ -0,0 +1,123 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import chalk from 'chalk';
+import { resolveWorkspace } from '../setup/workspace.js';
+
+function parseTask(filePath) {
+  const content = readFileSync(filePath, 'utf8');
+  const lines = content.split('\n');
+  
+  const task = {
+    title: '',
+    description: '',
+    status: '',
+    assignee: '',
+    due: '',
+    autonomy: 'draft',
+    created: ''
+  };
+  
+  let inFrontmatter = false;
+  
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    
+    if (line === '---') {
+      inFrontmatter = !inFrontmatter;
+      continue;
+    }
+    
+    if (inFrontmatter) {
+      const [key, ...valueParts] = line.split(':');
+      const value = valueParts.join(':').trim();
+      
+      if (key === 'title') task.title = value;
+      else if (key === 'description') task.description = value;
+      else if (key === 'status') task.status = value;
+      else if (key === 'assignee') task.assignee = value;
+      else if (key === 'due') task.due = value;
+      else if (key === 'autonomy') task.autonomy = value;
+      else if (key === 'created') task.created = value;
+    }
+  }
+  
+  return task;
+}
+
+export default async function active(options) {
+  // Try to resolve workspace, fallback to ~/pms for compatibility
+  let workspacePath = resolveWorkspace();
+  
+  if (!workspacePath) {
+    // Fallback to ~/pms (common default)
+    const fallbackPath = join(homedir(), 'pms');
+    if (existsSync(join(fallbackPath, 'projects'))) {
+      workspacePath = fallbackPath;
+    }
+  }
+  
+  if (!workspacePath) {
+    console.error(chalk.red('Error:'), 'No workspace found. Run:', chalk.cyan('cairn init'));
+    process.exit(1);
+  }
+  
+  const projectsDir = join(workspacePath, 'projects');
+  
+  if (!existsSync(projectsDir)) {
+    console.log(chalk.yellow('No projects found'));
+    return;
+  }
+  
+  const projects = readdirSync(projectsDir).filter(item => {
+    const path = join(projectsDir, item);
+    return statSync(path).isDirectory();
+  });
+  
+  const activeTasks = [];
+  
+  for (const project of projects) {
+    const tasksDir = join(projectsDir, project, 'tasks');
+    
+    if (!existsSync(tasksDir)) continue;
+    
+    const taskFiles = readdirSync(tasksDir).filter(f => f.endsWith('.md'));
+    
+    for (const taskFile of taskFiles) {
+      const taskPath = join(tasksDir, taskFile);
+      const task = parseTask(taskPath);
+      
+      if (task.status === 'in_progress') {
+        activeTasks.push({
+          project,
+          slug: taskFile.replace('.md', ''),
+          ...task
+        });
+      }
+    }
+  }
+  
+  if (activeTasks.length === 0) {
+    console.log(chalk.dim('No tasks in progress'));
+    return;
+  }
+  
+  console.log(chalk.cyan.bold('\n🚀 Active Tasks\n'));
+  
+  for (const task of activeTasks) {
+    console.log(chalk.bold(task.slug));
+    console.log(chalk.dim(`  ${task.project} • ${task.assignee || 'unassigned'}`));
+    if (task.description) {
+      console.log(`  ${task.description}`);
+    }
+    if (task.due) {
+      const dueDate = new Date(task.due);
+      const today = new Date();
+      const isOverdue = dueDate < today;
+      console.log(chalk.dim(`  Due: ${task.due}`) + (isOverdue ? chalk.red(' ⚠ OVERDUE') : ''));
+    }
+    console.log();
+  }
+  
+  console.log(chalk.dim(`${activeTasks.length} task${activeTasks.length === 1 ? '' : 's'} in progress`));
+}

package/lib/commands/artifact.js

@@ -0,0 +1,132 @@
+import { existsSync, writeFileSync, mkdirSync } from 'fs';
+import { homedir } from 'os';
+import { join, basename } from 'path';
+import { exec } from 'child_process';
+import chalk from 'chalk';
+import { resolveWorkspace } from '../setup/workspace.js';
+import { findTaskBySlug } from '../utils/task-helpers.js';
+
+// Get Obsidian vault path from environment or default
+function getObsidianVaultPath() {
+  // Check for OBSIDIAN_VAULT env var
+  if (process.env.OBSIDIAN_VAULT) {
+    return process.env.OBSIDIAN_VAULT;
+  }
+  
+  // Default to ~/Obsidian/pagoda (common setup)
+  return join(homedir(), 'Obsidian', 'pagoda');
+}
+
+function getObsidianVaultName() {
+  // Check for OBSIDIAN_VAULT_NAME env var
+  if (process.env.OBSIDIAN_VAULT_NAME) {
+    return process.env.OBSIDIAN_VAULT_NAME;
+  }
+  
+  // Default
+  return 'pagoda';
+}
+
+export default async function artifact(taskSlug, artifactName, options) {
+  // Try to resolve workspace, fallback to ~/pms for compatibility
+  let workspacePath = resolveWorkspace();
+  
+  if (!workspacePath) {
+    // Fallback to ~/pms (common default)
+    const fallbackPath = join(homedir(), 'pms');
+    if (existsSync(join(fallbackPath, 'projects'))) {
+      workspacePath = fallbackPath;
+    }
+  }
+  
+  if (!workspacePath) {
+    console.error(chalk.red('Error:'), 'No workspace found. Run:', chalk.cyan('cairn init'));
+    process.exit(1);
+  }
+  
+  if (!taskSlug) {
+    console.error(chalk.red('Error:'), 'Missing task slug');
+    console.log(chalk.dim('Usage:'), chalk.cyan('cairn artifact <task-slug> <artifact-name>'));
+    console.log(chalk.dim('Example:'), chalk.cyan('cairn artifact implement-auth "API Design"'));
+    process.exit(1);
+  }
+  
+  if (!artifactName) {
+    console.error(chalk.red('Error:'), 'Missing artifact name');
+    console.log(chalk.dim('Usage:'), chalk.cyan('cairn artifact <task-slug> <artifact-name>'));
+    console.log(chalk.dim('Example:'), chalk.cyan('cairn artifact implement-auth "API Design"'));
+    process.exit(1);
+  }
+  
+  // Find the task
+  const task = findTaskBySlug(workspacePath, taskSlug, options.project);
+  
+  if (!task) {
+    if (options.project) {
+      console.error(chalk.red('Error:'), `Task "${taskSlug}" not found in project "${options.project}"`);
+    } else {
+      console.error(chalk.red('Error:'), `Task "${taskSlug}" not found in any project`);
+      console.log(chalk.dim('Tip:'), 'Use', chalk.cyan('--project <slug>'), 'to search within a specific project');
+    }
+    process.exit(1);
+  }
+  
+  // Get Obsidian vault path
+  const vaultPath = getObsidianVaultPath();
+  const vaultName = getObsidianVaultName();
+  
+  if (!existsSync(vaultPath)) {
+    console.error(chalk.red('Error:'), `Obsidian vault not found at: ${vaultPath}`);
+    console.log(chalk.dim('Set OBSIDIAN_VAULT environment variable to your vault path'));
+    process.exit(1);
+  }
+  
+  // Create Artifacts directory if it doesn't exist
+  const artifactsDir = join(vaultPath, 'Artifacts');
+  if (!existsSync(artifactsDir)) {
+    mkdirSync(artifactsDir, { recursive: true });
+  }
+  
+  // Sanitize artifact name for filename
+  const filename = artifactName.replace(/[^a-z0-9-]/gi, ' ').trim().replace(/\s+/g, ' ') + '.md';
+  const artifactPath = join(artifactsDir, filename);
+  
+  // Create the artifact file if it doesn't exist
+  if (!existsSync(artifactPath)) {
+    const content = `# ${artifactName}\n\n*Artifact for task: ${taskSlug}*\n\n`;
+    writeFileSync(artifactPath, content, 'utf8');
+    console.log(chalk.green('✓'), 'Created artifact:', chalk.cyan(filename));
+  } else {
+    console.log(chalk.yellow('ℹ'), 'Artifact already exists:', chalk.cyan(filename));
+  }
+  
+  // Generate obsidian:// URL
+  const encodedFilename = encodeURIComponent(`Artifacts/${filename.replace('.md', '')}`);
+  const obsidianUrl = `obsidian://open?vault=${vaultName}&file=${encodedFilename}`;
+  
+  console.log(chalk.dim('Obsidian URL:'), obsidianUrl);
+  
+  // Add artifact to task using cairn update command
+  const updateCommand = `cd ${workspacePath} && cairn update ${taskSlug} --add-artifact "${obsidianUrl}"${options.project ? ` --project ${options.project}` : ''}`;
+  
+  exec(updateCommand, (error, stdout, stderr) => {
+    if (error) {
+      console.error(chalk.red('Error:'), 'Failed to add artifact to task');
+      console.error(stderr);
+      process.exit(1);
+    }
+    
+    console.log(stdout);
+    
+    // Open in Obsidian if --open flag is set
+    if (options.open) {
+      exec(`open "${obsidianUrl}"`, (openError) => {
+        if (openError) {
+          console.log(chalk.yellow('Could not auto-open Obsidian. Use the URL above.'));
+        } else {
+          console.log(chalk.green('✓'), 'Opened in Obsidian');
+        }
+      });
+    }
+  });
+}

package/lib/commands/block.js

@@ -0,0 +1,66 @@
+import { existsSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import chalk from 'chalk';
+import { resolveWorkspace } from '../setup/workspace.js';
+import { findTaskBySlug, updateTaskStatus, addLogEntry } from '../utils/task-helpers.js';
+
+export default async function block(taskSlug, message, options) {
+  // Try to resolve workspace, fallback to ~/pms for compatibility
+  let workspacePath = resolveWorkspace();
+  
+  if (!workspacePath) {
+    // Fallback to ~/pms (common default)
+    const fallbackPath = join(homedir(), 'pms');
+    if (existsSync(join(fallbackPath, 'projects'))) {
+      workspacePath = fallbackPath;
+    }
+  }
+  
+  if (!workspacePath) {
+    console.error(chalk.red('Error:'), 'No workspace found. Run:', chalk.cyan('cairn init'));
+    process.exit(1);
+  }
+  
+  if (!taskSlug) {
+    console.error(chalk.red('Error:'), 'Missing task slug');
+    console.log(chalk.dim('Usage:'), chalk.cyan('cairn block <task-slug> <message>'));
+    console.log(chalk.dim('Example:'), chalk.cyan('cairn block implement-auth "Waiting for API credentials"'));
+    process.exit(1);
+  }
+  
+  if (!message) {
+    console.error(chalk.red('Error:'), 'Missing blocker message');
+    console.log(chalk.dim('Usage:'), chalk.cyan('cairn block <task-slug> <message>'));
+    console.log(chalk.dim('Example:'), chalk.cyan('cairn block implement-auth "Waiting for API credentials"'));
+    process.exit(1);
+  }
+  
+  // Find the task
+  const task = findTaskBySlug(workspacePath, taskSlug, options.project);
+  
+  if (!task) {
+    if (options.project) {
+      console.error(chalk.red('Error:'), `Task "${taskSlug}" not found in project "${options.project}"`);
+    } else {
+      console.error(chalk.red('Error:'), `Task "${taskSlug}" not found in any project`);
+      console.log(chalk.dim('Tip:'), 'Use', chalk.cyan('--project <slug>'), 'to search within a specific project');
+    }
+    process.exit(1);
+  }
+  
+  try {
+    // Update status to blocked
+    updateTaskStatus(task.path, 'blocked');
+    
+    // Add log entry explaining the blocker
+    addLogEntry(task.path, `**BLOCKED:** ${message}`, 'Blocked');
+    
+    console.log(chalk.yellow('⚠'), `Task blocked: ${chalk.cyan(taskSlug)}`);
+    console.log(chalk.dim(`  Project: ${task.project}`));
+    console.log(chalk.dim(`  Blocker: ${message}`));
+  } catch (error) {
+    console.error(chalk.red('Error:'), `Failed to block task: ${error.message}`);
+    process.exit(1);
+  }
+}

package/lib/commands/create.js

@@ -3,6 +3,7 @@ import { join } from 'path';
 import chalk from 'chalk';
 import inquirer from 'inquirer';
 import { resolveWorkspace } from '../setup/workspace.js';
+import { VALID_STATUSES, VALID_AUTONOMY_LEVELS, validateTaskFrontmatter } from '../schema/task-schema.js';
 
 function expandNewlines(text) {
   if (!text) return text;
@@ -26,6 +27,11 @@ function getDueDate(daysFromNow = 7) {
   return date.toISOString().split('T')[0];
 }
 
+function getSmartDueDate(priority) {
+  // P1 = today (urgent), P2+ = 7 days (less urgent)
+  return priority === 1 ? getToday() : getDueDate(7);
+}
+
 export default async function create(type, name, options) {
   const workspacePath = resolveWorkspace();
 
@@ -157,25 +163,60 @@ async function createTask(workspacePath, name, slug, options) {
   }
 
   // Validate autonomy level if provided
-  const validAutonomy = ['propose', 'draft', 'execute'];
-  const autonomy = options.autonomy || 'draft';
-  if (!validAutonomy.includes(autonomy)) {
+  const autonomy = options.autonomy || 'execute';
+  if (!VALID_AUTONOMY_LEVELS.includes(autonomy)) {
     console.error(chalk.red('Error:'), `Invalid autonomy level: ${autonomy}`);
-    console.log(chalk.dim('Valid values:'), validAutonomy.join(', '));
+    console.log(chalk.dim('Valid values:'), VALID_AUTONOMY_LEVELS.join(', '));
+    process.exit(1);
+  }
+  
+  // Validate status if provided
+  const status = options.status || 'pending';
+  if (!VALID_STATUSES.includes(status)) {
+    console.error(chalk.red('Error:'), `Invalid status: ${status}`);
+    console.log(chalk.dim('Valid values:'), VALID_STATUSES.join(', '));
     process.exit(1);
   }
 
-  // Create task file
+  // Create task file with validated values
+  // Keep original name for title (human readable), slug for filename
   const taskSection = (text) => text ? `\n${expandNewlines(text)}\n` : '\n';
+  const priority = options.priority !== undefined ? parseInt(options.priority, 10) : 1;
+  const taskFrontmatter = {
+    title: name,  // Keep human-readable name
+    description: expandNewlines(options.description) || name,
+    assignee: options.assignee || 'you',
+    status: status,
+    priority: priority,
+    created: getToday(),
+    due: options.due || getSmartDueDate(priority),  // P1=today, P2+=7 days
+    autonomy: autonomy,
+    spend: 0,
+    artifacts: []
+  };
+  
+  // Validate frontmatter before creating file
+  const errors = validateTaskFrontmatter(taskFrontmatter);
+  if (errors.length > 0) {
+    console.error(chalk.red('Error:'), 'Task frontmatter validation failed:');
+    errors.forEach(err => console.log(chalk.red('  •'), err));
+    process.exit(1);
+  }
+  
+  // Quote title if it contains special YAML characters
+  const needsQuotes = name.includes(':') || name.includes('"') || name.includes('#');
+  const titleValue = needsQuotes ? `"${name.replace(/"/g, '\\"')}"` : name;
+  
   const task = `---
-title: ${name}
-description: ${expandNewlines(options.description) || name}
-assignee: ${options.assignee || 'you'}
-status: ${options.status || 'pending'}
-created: ${getToday()}
-due: ${options.due || getDueDate(7)}
-autonomy: ${autonomy}
-spend: 0
+title: ${titleValue}
+description: ${taskFrontmatter.description}
+assignee: ${taskFrontmatter.assignee}
+status: ${taskFrontmatter.status}
+priority: ${taskFrontmatter.priority}
+created: ${taskFrontmatter.created}
+due: ${taskFrontmatter.due}
+autonomy: ${taskFrontmatter.autonomy}
+spend: ${taskFrontmatter.spend}
 artifacts: []
 ---
 

package/lib/commands/done.js

@@ -0,0 +1,63 @@
+import { existsSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import chalk from 'chalk';
+import { resolveWorkspace } from '../setup/workspace.js';
+import { findTaskBySlug, updateTaskStatus, getTaskAutonomy } from '../utils/task-helpers.js';
+
+export default async function done(taskSlug, options) {
+  // Try to resolve workspace, fallback to ~/pms for compatibility
+  let workspacePath = resolveWorkspace();
+  
+  if (!workspacePath) {
+    // Fallback to ~/pms (common default)
+    const fallbackPath = join(homedir(), 'pms');
+    if (existsSync(join(fallbackPath, 'projects'))) {
+      workspacePath = fallbackPath;
+    }
+  }
+  
+  if (!workspacePath) {
+    console.error(chalk.red('Error:'), 'No workspace found. Run:', chalk.cyan('cairn init'));
+    process.exit(1);
+  }
+  
+  if (!taskSlug) {
+    console.error(chalk.red('Error:'), 'Missing task slug');
+    console.log(chalk.dim('Usage:'), chalk.cyan('cairn done <task-slug>'));
+    console.log(chalk.dim('Example:'), chalk.cyan('cairn done implement-auth'));
+    process.exit(1);
+  }
+  
+  // Find the task
+  const task = findTaskBySlug(workspacePath, taskSlug, options.project);
+  
+  if (!task) {
+    if (options.project) {
+      console.error(chalk.red('Error:'), `Task "${taskSlug}" not found in project "${options.project}"`);
+    } else {
+      console.error(chalk.red('Error:'), `Task "${taskSlug}" not found in any project`);
+      console.log(chalk.dim('Tip:'), 'Use', chalk.cyan('--project <slug>'), 'to search within a specific project');
+    }
+    process.exit(1);
+  }
+  
+  // Get task autonomy level to determine final status
+  const autonomy = getTaskAutonomy(task.path);
+  const finalStatus = autonomy === 'execute' ? 'done' : 'review';
+  
+  try {
+    updateTaskStatus(task.path, finalStatus);
+    
+    console.log(chalk.green('✓'), `Task completed: ${chalk.cyan(taskSlug)}`);
+    console.log(chalk.dim(`  Project: ${task.project}`));
+    console.log(chalk.dim(`  Status: ${finalStatus}`), chalk.dim(`(autonomy: ${autonomy})`));
+    
+    if (finalStatus === 'review') {
+      console.log(chalk.yellow('  →'), 'Task moved to review - awaiting approval');
+    }
+  } catch (error) {
+    console.error(chalk.red('Error:'), `Failed to complete task: ${error.message}`);
+    process.exit(1);
+  }
+}