cairn-work 1.0.1 → 1.1.0

package/README.md

@@ -1,5 +1,9 @@
 # Cairn
 
+[![npm version](https://img.shields.io/npm/v/cairn-work.svg)](https://www.npmjs.com/package/cairn-work)
+[![GitHub Discussions](https://img.shields.io/github/discussions/letcairnwork/cairn-cli)](https://github.com/letcairnwork/cairn-cli/discussions)
+[![Follow @letcairnwork](https://img.shields.io/twitter/follow/letcairnwork?style=social)](https://x.com/letcairnwork)
+
 Project management for AI agents. Markdown files are the source of truth.
 
 ## Setup
@@ -310,6 +314,28 @@ cairn log implement-auth "Implemented OAuth2 flow with GitHub provider"
 cairn log implement-auth "Fixed edge case in token refresh" --title "Bug Fix"
 ```
 
+### `cairn comment`
+
+Add a comment that syncs to the Cairn app (visible in the web UI).
+
+```bash
+# Status update
+cairn comment implement-auth "Started OAuth implementation"
+
+# Ask a question
+cairn comment implement-auth "Should we support Google SSO?" --type question
+
+# Worker handoff
+cairn comment implement-auth "Ready for code review" --type handoff --author "Engineer"
+```
+
+**Options:**
+- `--type <type>`: Comment type (`progress`, `question`, `handoff`, `comment`)
+- `--author <name>`: Author name (defaults to `$USER`)
+- `--author-type <type>`: `worker` or `human` (defaults to `worker`)
+
+Unlike `cairn note` (which writes to the task file), `cairn comment` writes to Convex and appears in the Cairn web app. Requires cairnsync authentication.
+
 ### `cairn update`
 
 Update task properties programmatically.
@@ -628,6 +654,24 @@ These files are auto-generated during `cairn onboard` and updated with `cairn up
 7. Task moves to `review` (if `autonomy: draft`) or `completed` (if `autonomy: execute`)
 8. Human: Reviews artifacts and approves work
 
+## Community & Support
+
+- **[GitHub Discussions](https://github.com/letcairnwork/cairn-cli/discussions)** — Ask questions, share ideas, show what you're building, and give feedback. This is the best place to connect.
+- **[GitHub Issues](https://github.com/letcairnwork/cairn-cli/issues)** — Bug reports only. For feature requests and questions, use Discussions.
+- **[Twitter/X @letcairnwork](https://x.com/letcairnwork)** — Follow for updates, or drop a quick question.
+
+New here? [Introduce yourself in Discussions](https://github.com/letcairnwork/cairn-cli/discussions/categories/introductions) — we'd love to hear what you're working on.
+
+## Contributing
+
+Contributions are welcome! If you have an idea for a feature or improvement, [start a discussion](https://github.com/letcairnwork/cairn-cli/discussions) first so we can talk through the approach before you invest time in a PR.
+
+Found a bug? [Open an issue](https://github.com/letcairnwork/cairn-cli/issues).
+
+## What's Next
+
+The roadmap is shaped by community feedback. If there's something you'd like to see, [request it in Discussions](https://github.com/letcairnwork/cairn-cli/discussions/categories/ideas).
+
 ## License
 
 MIT

package/bin/cairn.js

@@ -42,6 +42,7 @@ import search from '../lib/commands/search.js';
 import triage from '../lib/commands/triage.js';
 import learn from '../lib/commands/learn.js';
 import worker from '../lib/commands/worker.js';
+import comment from '../lib/commands/comment.js';
 
 // Onboard command - workspace setup with context files
 program
@@ -162,6 +163,16 @@ program
   .option('--project <slug>', 'Project to search for the task')
   .action(note);
 
+// Comment command - add comment to Convex (shows in app)
+program
+  .command('comment <task-slug> <message>')
+  .description('Add a comment to task (syncs to Cairn app)')
+  .option('--project <slug>', 'Project to search for the task')
+  .option('--type <type>', 'Comment type: question, progress, handoff, or comment', 'progress')
+  .option('--author <name>', 'Author name (defaults to $USER)')
+  .option('--author-type <type>', 'Author type: human or worker', 'worker')
+  .action(comment);
+
 // View command - show full task details
 program
   .command('view <task-slug>')

package/bin/postinstall.js

@@ -51,5 +51,11 @@ try {
     log();
   }
 } catch {
-  process.exit(0);
+  // fall through
 }
+
+log();
+log('  \x1b[36mThanks for installing Cairn!\x1b[0m');
+log('  Join the community: \x1b[4mhttps://github.com/letcairnwork/cairn-cli/discussions\x1b[0m');
+log('  Follow for updates: \x1b[4mhttps://x.com/letcairnwork\x1b[0m');
+log();

package/lib/commands/comment.js

@@ -0,0 +1,186 @@
+import { existsSync, readFileSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import chalk from 'chalk';
+import { resolveWorkspace } from '../setup/workspace.js';
+import { findTaskBySlug, getAgentName } from '../utils/task-helpers.js';
+
+const CONVEX_URL = 'https://admired-wildebeest-654.convex.cloud';
+
+/**
+ * Decode JWT payload without validation (for extracting userId)
+ */
+function decodeJwtPayload(token) {
+  try {
+    const parts = token.split('.');
+    if (parts.length !== 3) return null;
+    const payload = Buffer.from(parts[1], 'base64url').toString('utf-8');
+    return JSON.parse(payload);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Load auth token from workspace .cairn-token.json
+ */
+function loadAuthToken(workspacePath) {
+  const tokenPath = join(workspacePath, '.cairn-token.json');
+  
+  if (!existsSync(tokenPath)) {
+    return null;
+  }
+  
+  try {
+    const raw = readFileSync(tokenPath, 'utf-8');
+    const data = JSON.parse(raw);
+    
+    if (!data.accessToken) {
+      return null;
+    }
+    
+    // Check if token is expired
+    if (data.expiresAt && Date.now() >= data.expiresAt) {
+      return null;
+    }
+    
+    return data.accessToken;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build task path from project and slug
+ */
+function buildTaskPath(project, taskSlug) {
+  return `projects/${project}/tasks/${taskSlug}.md`;
+}
+
+/**
+ * Call Convex mutation via HTTP
+ */
+async function callConvexMutation(functionName, args, token) {
+  const url = `${CONVEX_URL}/api/mutation`;
+  
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${token}`,
+    },
+    body: JSON.stringify({
+      path: functionName,
+      args,
+      format: 'json',
+    }),
+  });
+  
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Convex API error (${response.status}): ${text}`);
+  }
+  
+  const result = await response.json();
+  
+  if (result.status === 'error') {
+    throw new Error(result.errorMessage || 'Unknown Convex error');
+  }
+  
+  return result.value;
+}
+
+export default async function comment(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 onboard'));
+    process.exit(1);
+  }
+  
+  if (!taskSlug) {
+    console.error(chalk.red('Error:'), 'Missing task slug');
+    console.log(chalk.dim('Usage:'), chalk.cyan('cairn comment <task-slug> <message>'));
+    console.log(chalk.dim('Example:'), chalk.cyan('cairn comment implement-auth "Found a bug in OAuth flow"'));
+    process.exit(1);
+  }
+  
+  if (!message) {
+    console.error(chalk.red('Error:'), 'Missing comment message');
+    console.log(chalk.dim('Usage:'), chalk.cyan('cairn comment <task-slug> <message>'));
+    console.log(chalk.dim('Example:'), chalk.cyan('cairn comment implement-auth "Found a bug in OAuth flow"'));
+    process.exit(1);
+  }
+  
+  // Find the task to get the correct project
+  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);
+  }
+  
+  // Load auth token
+  const token = loadAuthToken(workspacePath);
+  
+  if (!token) {
+    console.error(chalk.red('Error:'), 'Not authenticated. Cairn sync must be running and logged in.');
+    console.log(chalk.dim('Tip:'), 'Run', chalk.cyan('cairnsync auth login'), 'to authenticate');
+    process.exit(1);
+  }
+  
+  // Decode token to get userId
+  const payload = decodeJwtPayload(token);
+  
+  if (!payload || !payload.sub) {
+    console.error(chalk.red('Error:'), 'Invalid auth token. Please re-authenticate.');
+    console.log(chalk.dim('Tip:'), 'Run', chalk.cyan('cairnsync auth login'), 'to re-authenticate');
+    process.exit(1);
+  }
+  
+  const userId = payload.sub;
+  
+  // Determine author info
+  const authorName = options.author || getAgentName();
+  const authorType = options.authorType || 'worker';
+  const authorId = authorType === 'human' ? userId : authorName.toLowerCase();
+  const commentType = options.type || 'progress';
+  
+  // Build task path as Convex expects it
+  const taskPath = buildTaskPath(task.project, taskSlug);
+  
+  try {
+    const result = await callConvexMutation('taskComments:add', {
+      taskPath,
+      userId,
+      authorId,
+      authorType,
+      authorName,
+      content: message,
+      commentType,
+    }, token);
+    
+    console.log(chalk.green('✓'), `Comment added to task: ${chalk.cyan(taskSlug)}`);
+    console.log(chalk.dim(`  Project: ${task.project}`));
+    console.log(chalk.dim(`  Author: ${authorName} (${authorType})`));
+    console.log(chalk.dim(`  Type: ${commentType}`));
+    console.log(chalk.dim(`  Message: ${message.length > 60 ? message.substring(0, 60) + '...' : message}`));
+  } catch (error) {
+    console.error(chalk.red('Error:'), `Failed to add comment: ${error.message}`);
+    process.exit(1);
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cairn-work",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "AI-native project management - optimized CLI for AI agents and humans working together",
   "type": "module",
   "bin": {
@@ -37,7 +37,7 @@
     "type": "git",
     "url": "https://github.com/letcairnwork/cairn-cli.git"
   },
-  "homepage": "https://letcairn.work",
+  "homepage": "https://cairn.quest",
   "bugs": {
     "url": "https://github.com/letcairnwork/cairn-cli/issues"
   },

package/templates/workspace/TOOLS.md.template

@@ -18,7 +18,7 @@ Things like:
 - front-door → Entrance, motion-triggered
 
 ### SSH
-- home-server → 192.168.1.100, user: admin
+- home-server → 10.0.0.1, user: deploy
 
 ### Cairn
 - Workspace: {{WORKSPACE_PATH}}