@masslessai/push-todo 3.0.0 → 3.2.0

package/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "push-todo",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "description": "Voice tasks from Push iOS app"
 }

package/hooks/session-end.js

@@ -26,7 +26,7 @@ function getApiKey() {
 
   try {
     const content = readFileSync(CONFIG_FILE, 'utf8');
-    const match = content.match(/^export\s+PUSH_KEY\s*=\s*["']?([^"'\n]+)["']?/m);
+    const match = content.match(/^export\s+PUSH_API_KEY\s*=\s*["']?([^"'\n]+)["']?/m);
     return match ? match[1] : null;
   } catch {
     return null;

package/hooks/session-start.js

@@ -2,16 +2,67 @@
 /**
  * Session start hook for Push CLI.
  *
- * Displays task count notification when Claude Code starts.
+ * 1. Ensures CLI is installed (for marketplace installations)
+ * 2. Displays task count notification when Claude Code starts
  */
 
-import { execSync } from 'child_process';
+import { execSync, spawnSync } from 'child_process';
 import { existsSync, readFileSync } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
 
 const CONFIG_FILE = join(homedir(), '.config', 'push', 'config');
 const API_BASE = 'https://jxuzqcbqhiaxmfitzxlo.supabase.co/functions/v1';
+const NPM_PACKAGE = '@masslessai/push-todo';
+
+/**
+ * Check if push-todo CLI is available.
+ */
+function isCLIInstalled() {
+  try {
+    execSync('which push-todo', {
+      encoding: 'utf8',
+      timeout: 3000,
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Install the CLI via npm (for marketplace installations).
+ */
+function ensureCLIInstalled() {
+  if (isCLIInstalled()) {
+    return true;
+  }
+
+  console.log(`[Push] Installing CLI tools...`);
+
+  try {
+    // Use spawnSync to allow npm to find itself
+    const result = spawnSync('npm', ['install', '-g', NPM_PACKAGE], {
+      encoding: 'utf8',
+      timeout: 60000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      shell: true
+    });
+
+    if (result.status === 0) {
+      console.log(`[Push] CLI installed successfully.`);
+      return true;
+    } else {
+      console.log(`[Push] CLI installation failed. Run manually: npm install -g ${NPM_PACKAGE}`);
+      return false;
+    }
+  } catch (error) {
+    console.log(`[Push] CLI installation failed: ${error.message}`);
+    console.log(`[Push] Run manually: npm install -g ${NPM_PACKAGE}`);
+    return false;
+  }
+}
 
 /**
  * Get the API key from config.
@@ -29,7 +80,7 @@ function getApiKey() {
 
   try {
     const content = readFileSync(CONFIG_FILE, 'utf8');
-    const match = content.match(/^export\s+PUSH_KEY\s*=\s*["']?([^"'\n]+)["']?/m);
+    const match = content.match(/^export\s+PUSH_API_KEY\s*=\s*["']?([^"'\n]+)["']?/m);
     return match ? match[1] : null;
   } catch {
     return null;
@@ -108,10 +159,16 @@ async function fetchTaskCount(apiKey, gitRemote) {
  * Main entry point.
  */
 async function main() {
+  // Step 1: Ensure CLI is installed (for marketplace installations)
+  // This is a no-op if CLI already exists (npm install path)
+  ensureCLIInstalled();
+
+  // Step 2: Check for API key
   const apiKey = getApiKey();
 
   if (!apiKey) {
-    // No API key - silent exit
+    // No API key - prompt to connect
+    console.log(`[Push] Run 'push-todo connect' to set up your account.`);
     process.exit(0);
   }
 

package/lib/api.js

@@ -118,12 +118,20 @@ export async function fetchTaskByNumber(displayNumber) {
  * @returns {Promise<boolean>} True if successful
  */
 export async function markTaskCompleted(taskId, comment = '') {
-  const response = await apiRequest('mark-todo-completed', {
-    method: 'POST',
-    body: JSON.stringify({
-      todo_id: taskId,
-      completion_comment: comment
-    })
+  const payload = {
+    todoId: taskId,
+    isCompleted: true,
+    completedAt: new Date().toISOString()
+  };
+
+  // Add completion comment if provided (appears in Push app timeline)
+  if (comment) {
+    payload.completionComment = comment;
+  }
+
+  const response = await apiRequest('todo-status', {
+    method: 'PATCH',
+    body: JSON.stringify(payload)
   });
 
   if (!response.ok) {
@@ -137,14 +145,18 @@ export async function markTaskCompleted(taskId, comment = '') {
 /**
  * Queue a task for daemon execution.
  *
+ * Sets execution_status to 'queued' via the update-task-execution endpoint.
+ * The daemon will pick it up on next poll.
+ *
  * @param {number} displayNumber - The task's display number
  * @returns {Promise<boolean>} True if successful
  */
 export async function queueTask(displayNumber) {
-  const response = await apiRequest('queue-task', {
-    method: 'POST',
+  const response = await apiRequest('update-task-execution', {
+    method: 'PATCH',
     body: JSON.stringify({
-      display_number: displayNumber
+      displayNumber: displayNumber,
+      status: 'queued'
     })
   });
 
@@ -153,7 +165,8 @@ export async function queueTask(displayNumber) {
     throw new Error(`Failed to queue task: ${text}`);
   }
 
-  return true;
+  const data = await response.json();
+  return data.success || false;
 }
 
 /**
@@ -189,7 +202,7 @@ export async function queueTasks(displayNumbers) {
  */
 export async function searchTasks(query, gitRemote = null) {
   const params = new URLSearchParams();
-  params.set('query', query);
+  params.set('q', query);  // Edge function expects 'q', not 'query'
   if (gitRemote) {
     params.set('git_remote', gitRemote);
   }
@@ -231,11 +244,16 @@ export async function updateTaskExecution(payload) {
 /**
  * Validate API key.
  *
+ * Uses synced-todos with limit=0 as a lightweight validation check.
+ * This matches the Python implementation approach.
+ *
  * @returns {Promise<Object>} Validation result with user info
  */
 export async function validateApiKey() {
   try {
-    const response = await apiRequest('validate-api-key');
+    // Use synced-todos with limit=0 as lightweight validation
+    // (no validate-api-key endpoint exists)
+    const response = await apiRequest('synced-todos?limit=0');
 
     if (!response.ok) {
       if (response.status === 401) {
@@ -244,11 +262,10 @@ export async function validateApiKey() {
       return { valid: false, reason: 'api_error' };
     }
 
-    const data = await response.json();
+    // Key is valid if request succeeds
+    // Note: synced-todos doesn't return user info, so we mark as valid without email
     return {
-      valid: true,
-      userId: data.user_id,
-      email: data.email
+      valid: true
     };
   } catch (error) {
     return { valid: false, reason: 'network_error', error: error.message };
@@ -322,4 +339,30 @@ export async function getLatestVersion() {
   }
 }
 
+/**
+ * Learn vocabulary terms for a task.
+ *
+ * The LLM determines WHAT keywords to send; this function handles HOW.
+ *
+ * @param {string} todoId - UUID of the task
+ * @param {string[]} keywords - List of vocabulary terms
+ * @returns {Promise<Object>} Result with keywords_added, keywords_duplicate, etc.
+ */
+export async function learnVocabulary(todoId, keywords) {
+  const response = await apiRequest('learn-keywords', {
+    method: 'POST',
+    body: JSON.stringify({
+      todo_id: todoId,
+      keywords
+    })
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Failed to learn vocabulary: ${text}`);
+  }
+
+  return response.json();
+}
+
 export { API_BASE };

package/lib/certainty.js

@@ -0,0 +1,434 @@
+/**
+ * Certainty Analyzer for Push Task Execution
+ *
+ * Analyzes todos to determine execution certainty based on multiple signals.
+ * High-certainty todos execute automatically; low-certainty todos trigger
+ * planning mode or prompt for clarification.
+ *
+ * Architecture:
+ * - Input: Task content, context, and metadata
+ * - Output: Certainty score (0.0-1.0) + confidence reasons + clarification questions
+ *
+ * Certainty Signals:
+ * 1. Content specificity - Does it clearly describe what to do?
+ * 2. Scope clarity - Is the scope well-defined (vs "improve performance")?
+ * 3. Codebase context - Does it reference specific files/functions?
+ * 4. Action verb presence - Does it start with actionable verbs?
+ * 5. Ambiguity markers - Are there question marks, "maybe", "or", etc.?
+ *
+ * Thresholds:
+ * - High certainty (>= 0.7): Execute immediately
+ * - Medium certainty (0.4-0.7): Execute with planning mode
+ * - Low certainty (< 0.4): Request clarification before execution
+ *
+ * Ported from: plugins/push-todo/scripts/certainty_analyzer.py
+ */
+
+// ==================== Constants ====================
+
+// High-confidence action verbs (imperative, specific)
+const HIGH_CONFIDENCE_VERBS = [
+  'add', 'create', 'implement', 'fix', 'update', 'remove', 'delete',
+  'rename', 'refactor', 'migrate', 'upgrade', 'install', 'configure',
+  'write', 'modify', 'change', 'replace', 'extract', 'move', 'copy',
+  'integrate', 'connect', 'disconnect', 'enable', 'disable', 'test'
+];
+
+// Low-confidence words (vague, uncertain)
+const LOW_CONFIDENCE_MARKERS = [
+  'maybe', 'possibly', 'might', 'could', 'should consider',
+  'think about', 'explore', 'investigate', 'look into',
+  'try to', 'attempt to', 'see if', 'check if',
+  'or something', 'or maybe', 'not sure', 'unclear',
+  'somehow', 'whatever', 'something like', 'kind of'
+];
+
+// Question patterns that indicate uncertainty
+const QUESTION_PATTERNS = [
+  /\?/,                                    // Direct questions
+  /\bwhat\s+(should|would|could)\b/i,
+  /\bhow\s+(should|would|could|do)\b/i,
+  /\bwhich\s+(one|approach|way|method)\b/i,
+  /\bis\s+it\s+(better|possible|ok)\b/i
+];
+
+// Specificity indicators (file paths, function names, etc.)
+const SPECIFICITY_PATTERNS = [
+  /\b[A-Z][a-zA-Z]+\.(swift|ts|tsx|py|js|jsx|go|rs|java|kt)\b/,  // File names
+  /\bfunc\s+\w+\b|\bfunction\s+\w+\b|\bdef\s+\w+\b/,              // Function defs
+  /\bclass\s+[A-Z][a-zA-Z]+\b/,                                    // Class names
+  /[a-zA-Z]+\.[a-zA-Z]+\(\)/,                                      // Method calls
+  /\/[a-zA-Z][a-zA-Z0-9_/\-.]+/,                                   // File paths
+  /\b(line|row)\s+\d+\b/,                                          // Line numbers
+  /#\d+/,                                                          // Issue/PR numbers
+  /\b(error|warning|bug)\s*:\s*\w+/                                // Error references
+];
+
+// Scope indicators that suggest well-defined tasks
+const SCOPE_INDICATORS = [
+  /\bin\s+(?:the\s+)?(\w+\.\w+|[\w/]+)\b/,                        // "in file.ts" or "in src/utils"
+  /\bfor\s+(?:the\s+)?(\w+)\s+(component|service|module|class|function)\b/,
+  /\bwhen\s+\w+/,                                                  // Condition-based scope
+  /\bonly\s+(for|in|when)\b/                                       // Explicit scope limitation
+];
+
+// ==================== Certainty Levels ====================
+
+export const CertaintyLevel = {
+  HIGH: 'high',      // >= 0.7: Execute immediately
+  MEDIUM: 'medium',  // 0.4-0.7: Execute with planning mode
+  LOW: 'low'         // < 0.4: Request clarification
+};
+
+// ==================== CertaintyAnalyzer Class ====================
+
+export class CertaintyAnalyzer {
+  constructor() {
+    // Base score starts at 0.5 (neutral)
+    this.baseScore = 0.5;
+  }
+
+  /**
+   * Analyze task content and return certainty assessment.
+   *
+   * @param {string} content - The normalized task content
+   * @param {string|null} summary - Optional task summary
+   * @param {string|null} transcript - Optional original voice transcript
+   * @returns {Object} CertaintyAnalysis with score, level, reasons, and questions
+   */
+  analyze(content, summary = null, transcript = null) {
+    // Combine all text for analysis
+    const fullText = this._combineText(content, summary, transcript);
+    const fullTextLower = fullText.toLowerCase();
+
+    const reasons = [];
+    const questions = [];
+    let score = this.baseScore;
+
+    // 1. Check for action verbs at the start
+    const [verbScore, verbReason] = this._checkActionVerbs(fullTextLower);
+    score += verbScore;
+    if (verbReason) reasons.push(verbReason);
+
+    // 2. Check for low-confidence markers
+    const [markerScore, markerReasons] = this._checkLowConfidenceMarkers(fullTextLower);
+    score += markerScore;
+    reasons.push(...markerReasons);
+
+    // 3. Check for questions/uncertainty
+    const [questionScore, questionReason, questionQ] = this._checkQuestions(fullTextLower);
+    score += questionScore;
+    if (questionReason) reasons.push(questionReason);
+    if (questionQ) questions.push(questionQ);
+
+    // 4. Check for specificity (file names, functions, etc.)
+    const [specScore, specReason] = this._checkSpecificity(fullText);
+    score += specScore;
+    if (specReason) reasons.push(specReason);
+
+    // 5. Check for scope clarity
+    const [scopeScore, scopeReason, scopeQ] = this._checkScope(fullTextLower);
+    score += scopeScore;
+    if (scopeReason) reasons.push(scopeReason);
+    if (scopeQ) questions.push(scopeQ);
+
+    // 6. Check content length (very short = potentially unclear)
+    const [lengthScore, lengthReason, lengthQ] = this._checkContentLength(content);
+    score += lengthScore;
+    if (lengthReason) reasons.push(lengthReason);
+    if (lengthQ) questions.push(lengthQ);
+
+    // 7. Check for multiple alternatives (indicates decision needed)
+    const [altScore, altReason, altQ] = this._checkAlternatives(fullTextLower);
+    score += altScore;
+    if (altReason) reasons.push(altReason);
+    if (altQ) questions.push(altQ);
+
+    // Clamp score to [0, 1]
+    score = Math.max(0.0, Math.min(1.0, score));
+
+    // Determine level
+    let level;
+    if (score >= 0.7) {
+      level = CertaintyLevel.HIGH;
+    } else if (score >= 0.4) {
+      level = CertaintyLevel.MEDIUM;
+    } else {
+      level = CertaintyLevel.LOW;
+    }
+
+    // Sort questions by priority (higher first)
+    questions.sort((a, b) => b.priority - a.priority);
+
+    // Determine recommended action
+    const recommendedAction = this._getRecommendedAction(level, questions);
+
+    return {
+      score: Math.round(score * 100) / 100,
+      level,
+      reasons,
+      clarificationQuestions: questions,
+      recommendedAction
+    };
+  }
+
+  _combineText(content, summary, transcript) {
+    const parts = [content];
+    if (summary) parts.push(summary);
+    if (transcript) parts.push(transcript);
+    return parts.join(' ');
+  }
+
+  _checkActionVerbs(text) {
+    const words = text.split(/\s+/);
+    if (words.length === 0) {
+      return [0.0, null];
+    }
+
+    const firstWord = words[0].replace(/[.,!?:;]/g, '');
+
+    if (HIGH_CONFIDENCE_VERBS.includes(firstWord)) {
+      return [0.15, {
+        factor: 'action_verb',
+        scoreDelta: 0.15,
+        explanation: `Starts with clear action verb: '${firstWord}'`
+      }];
+    }
+
+    // Check first 5 words for verb
+    for (const word of words.slice(0, 5)) {
+      const cleaned = word.replace(/[.,!?:;]/g, '');
+      if (HIGH_CONFIDENCE_VERBS.includes(cleaned)) {
+        return [0.08, {
+          factor: 'action_verb',
+          scoreDelta: 0.08,
+          explanation: `Contains action verb: '${cleaned}'`
+        }];
+      }
+    }
+
+    return [-0.1, {
+      factor: 'action_verb',
+      scoreDelta: -0.1,
+      explanation: 'No clear action verb found'
+    }];
+  }
+
+  _checkLowConfidenceMarkers(text) {
+    const reasons = [];
+    let totalDelta = 0.0;
+
+    for (const marker of LOW_CONFIDENCE_MARKERS) {
+      if (text.includes(marker)) {
+        const delta = -0.1;
+        totalDelta += delta;
+        reasons.push({
+          factor: 'uncertainty_marker',
+          scoreDelta: delta,
+          explanation: `Contains uncertainty marker: '${marker}'`
+        });
+        // Cap at -0.3 total
+        if (totalDelta <= -0.3) {
+          break;
+        }
+      }
+    }
+
+    return [totalDelta, reasons];
+  }
+
+  _checkQuestions(text) {
+    for (const pattern of QUESTION_PATTERNS) {
+      if (pattern.test(text)) {
+        return [-0.15, {
+          factor: 'question_present',
+          scoreDelta: -0.15,
+          explanation: 'Task contains questions or uncertainty'
+        }, {
+          question: 'The task seems to ask a question. Can you clarify what action to take?',
+          options: ['Investigate and recommend', 'Make a decision for me', 'Skip this task'],
+          priority: 2
+        }];
+      }
+    }
+    return [0.0, null, null];
+  }
+
+  _checkSpecificity(text) {
+    const matches = [];
+    for (const pattern of SPECIFICITY_PATTERNS) {
+      const found = text.match(pattern);
+      if (found) {
+        matches.push(found[0]);
+      }
+    }
+
+    if (matches.length >= 3) {
+      return [0.2, {
+        factor: 'high_specificity',
+        scoreDelta: 0.2,
+        explanation: `Multiple specific references found (${matches.length} items)`
+      }];
+    } else if (matches.length >= 1) {
+      return [0.1, {
+        factor: 'specificity',
+        scoreDelta: 0.1,
+        explanation: `Contains specific references: ${matches.slice(0, 3).join(', ')}`
+      }];
+    }
+
+    return [-0.05, {
+      factor: 'low_specificity',
+      scoreDelta: -0.05,
+      explanation: 'No specific file/function references found'
+    }];
+  }
+
+  _checkScope(text) {
+    const hasScope = SCOPE_INDICATORS.some(pattern => pattern.test(text));
+
+    // Check for overly broad terms
+    const broadTerms = ['everything', 'all files', 'entire', 'whole codebase',
+      'the system', 'performance', 'improve'];
+    const hasBroad = broadTerms.some(term => text.includes(term));
+
+    if (hasScope && !hasBroad) {
+      return [0.1, {
+        factor: 'clear_scope',
+        scoreDelta: 0.1,
+        explanation: 'Task has well-defined scope'
+      }, null];
+    } else if (hasBroad) {
+      return [-0.15, {
+        factor: 'broad_scope',
+        scoreDelta: -0.15,
+        explanation: 'Task scope is very broad'
+      }, {
+        question: 'The task scope seems broad. Can you narrow it down?',
+        options: ['Focus on most critical area', 'Start with a specific file',
+          'Analyze first, then decide'],
+        priority: 3
+      }];
+    }
+
+    return [0.0, null, null];
+  }
+
+  _checkContentLength(content) {
+    const words = content.split(/\s+/).filter(w => w.length > 0).length;
+
+    if (words < 5) {
+      return [-0.2, {
+        factor: 'very_short',
+        scoreDelta: -0.2,
+        explanation: `Task description very short (${words} words)`
+      }, {
+        question: 'Can you provide more detail about what specifically needs to be done?',
+        options: [],
+        priority: 4
+      }];
+    } else if (words < 10) {
+      return [-0.05, {
+        factor: 'short',
+        scoreDelta: -0.05,
+        explanation: `Task description brief (${words} words)`
+      }, null];
+    } else if (words > 50) {
+      return [0.1, {
+        factor: 'detailed',
+        scoreDelta: 0.1,
+        explanation: 'Task has detailed description'
+      }, null];
+    }
+
+    return [0.0, null, null];
+  }
+
+  _checkAlternatives(text) {
+    const altPatterns = [
+      /\bor\s+\w+\b.*\bor\s+\w+\b/i,  // Multiple "or"s
+      /\beither\b.*\bor\b/i,
+      /option\s*[a-d1-4]/i,
+      /\balternative(ly)?\b/i,
+      /\bversus\b|\bvs\.?\b/i
+    ];
+
+    for (const pattern of altPatterns) {
+      if (pattern.test(text)) {
+        return [-0.15, {
+          factor: 'multiple_alternatives',
+          scoreDelta: -0.15,
+          explanation: 'Task presents multiple alternatives'
+        }, {
+          question: 'Which approach should I take?',
+          options: [],
+          priority: 5
+        }];
+      }
+    }
+
+    return [0.0, null, null];
+  }
+
+  _getRecommendedAction(level, questions) {
+    if (level === CertaintyLevel.HIGH) {
+      return 'execute';
+    } else if (level === CertaintyLevel.MEDIUM) {
+      return 'execute_with_plan';
+    } else {
+      if (questions.length > 0) {
+        return 'clarify';
+      }
+      return 'skip_or_clarify';
+    }
+  }
+}
+
+// ==================== Convenience Functions ====================
+
+/**
+ * Convenience function to analyze task certainty.
+ *
+ * @param {string} content - The normalized task content
+ * @param {string|null} summary - Optional task summary
+ * @param {string|null} transcript - Optional original voice transcript
+ * @returns {Object} CertaintyAnalysis with score, level, reasons, and questions
+ */
+export function analyzeCertainty(content, summary = null, transcript = null) {
+  const analyzer = new CertaintyAnalyzer();
+  return analyzer.analyze(content, summary, transcript);
+}
+
+/**
+ * Quick check if task should be executed.
+ *
+ * @param {string} content - The normalized task content
+ * @param {string|null} summary - Optional task summary
+ * @param {string|null} transcript - Optional original voice transcript
+ * @param {number} threshold - Minimum certainty score (default 0.4 = medium confidence)
+ * @returns {boolean} True if task certainty meets threshold
+ */
+export function shouldExecute(content, summary = null, transcript = null, threshold = 0.4) {
+  const analysis = analyzeCertainty(content, summary, transcript);
+  return analysis.score >= threshold;
+}
+
+/**
+ * Get execution mode based on certainty.
+ *
+ * @param {Object} analysis - CertaintyAnalysis result
+ * @returns {string} 'immediate' | 'planning' | 'clarify'
+ */
+export function getExecutionMode(analysis) {
+  if (!analysis) {
+    return 'immediate';
+  }
+
+  if (analysis.score >= 0.7) {
+    return 'immediate';
+  } else if (analysis.score >= 0.4) {
+    return 'planning';
+  } else {
+    return 'clarify';
+  }
+}