@simonfestl/husky-cli 1.7.0 → 1.9.1

package/dist/lib/biz/qdrant.js

@@ -15,21 +15,23 @@ export class QdrantClient {
     }
     /**
      * Create client from Husky config
-     * Priority: PROD_* env vars > env vars > local config
+     * Priority: HUSKY_QDRANT_URL (VM standard) > PROD_* env vars > config > localhost
      */
     static fromConfig() {
         const config = getConfig();
         const env = process.env.HUSKY_ENV || 'PROD';
         const qdrantConfig = {
-            url: process.env[`${env}_QDRANT_URL`] || process.env.QDRANT_URL || config.qdrantUrl || 'http://localhost:6333',
+            // Priority: HUSKY_QDRANT_URL (VM standard) > PROD_QDRANT_URL > config > localhost
+            url: process.env.HUSKY_QDRANT_URL || process.env[`${env}_QDRANT_URL`] || process.env.QDRANT_URL || config.qdrantUrl || 'http://localhost:6333',
+            // API key optional - internal Qdrant VM is VPC secured
             apiKey: process.env[`${env}_QDRANT_API_KEY`] || process.env.QDRANT_API_KEY || config.qdrantApiKey,
         };
         if (!qdrantConfig.url || qdrantConfig.url === 'http://localhost:6333') {
-            if (!process.env.QDRANT_URL && !process.env[`${env}_QDRANT_URL`]) {
+            if (!process.env.QDRANT_URL && !process.env[`${env}_QDRANT_URL`] && !process.env.HUSKY_QDRANT_URL) {
                 throw new Error('Missing Qdrant URL. Configure with:\n' +
-                    '  husky config set qdrant-url <url>\n' +
-                    '  husky config set qdrant-api-key <key>\n' +
-                    'Or set env vars: PROD_QDRANT_URL, PROD_QDRANT_API_KEY');
+                    '  husky config set qdrant-url http://10.132.0.46:6333\n' +
+                    'Or set env var: HUSKY_QDRANT_URL\n\n' +
+                    'Note: Internal Qdrant VM - no API key needed (VPC secured)');
             }
         }
         return new QdrantClient(qdrantConfig);
@@ -153,6 +155,15 @@ export class QdrantClient {
             body: JSON.stringify({ points: ids }),
         });
     }
+    async setPayload(collectionName, pointId, payload) {
+        await this.request(`/collections/${collectionName}/points/payload?wait=true`, {
+            method: 'POST',
+            body: JSON.stringify({
+                points: [pointId],
+                payload,
+            }),
+        });
+    }
     async count(collectionName) {
         const info = await this.getCollection(collectionName);
         return info.pointsCount;

package/dist/lib/biz/sop-generator.d.ts

@@ -0,0 +1,39 @@
+/**
+ * SOP (Standard Operating Procedure) Generator
+ *
+ * Generates SOPs from agent learnings using LLM.
+ * Leverages PII-free embeddings for safe processing.
+ */
+import { AgentType } from './agent-brain.js';
+export interface SOPGenerationOptions {
+    topic: string;
+    agentType?: AgentType;
+    minMemories?: number;
+    format?: 'markdown' | 'json';
+}
+export interface SOPSection {
+    title: string;
+    content: string;
+    examples?: string[];
+}
+export interface SOP {
+    title: string;
+    topic: string;
+    sections: SOPSection[];
+    sourceCount: number;
+    generatedAt: string;
+}
+/**
+ * Generate SOP from learnings
+ *
+ * TODO: In future, use Vertex AI/Gemini to:
+ * 1. Recall relevant memories by topic
+ * 2. Group and cluster similar learnings
+ * 3. Extract patterns and best practices
+ * 4. Generate structured SOP document
+ */
+export declare function generateSOP(agentId: string, options: SOPGenerationOptions): Promise<SOP>;
+/**
+ * Format SOP as Markdown
+ */
+export declare function formatSOPAsMarkdown(sop: SOP): string;

package/dist/lib/biz/sop-generator.js

@@ -0,0 +1,131 @@
+/**
+ * SOP (Standard Operating Procedure) Generator
+ *
+ * Generates SOPs from agent learnings using LLM.
+ * Leverages PII-free embeddings for safe processing.
+ */
+import { AgentBrain } from './agent-brain.js';
+/**
+ * Generate SOP from learnings
+ *
+ * TODO: In future, use Vertex AI/Gemini to:
+ * 1. Recall relevant memories by topic
+ * 2. Group and cluster similar learnings
+ * 3. Extract patterns and best practices
+ * 4. Generate structured SOP document
+ */
+export async function generateSOP(agentId, options) {
+    const { topic, agentType, minMemories = 5, format = 'markdown' } = options;
+    // Initialize brain
+    const brain = new AgentBrain({ agentId, agentType });
+    // Recall memories related to topic
+    const results = await brain.recall(topic, 50, 0.3);
+    if (results.length < minMemories) {
+        throw new Error(`Not enough learnings found for topic "${topic}" (found ${results.length}, need ${minMemories})`);
+    }
+    // Group memories by tags
+    const grouped = groupMemoriesByTags(results.map(r => r.memory));
+    // Generate SOP sections (basic version - TODO: use LLM for better structure)
+    const sections = [];
+    for (const [tag, memories] of Object.entries(grouped)) {
+        sections.push({
+            title: formatTagAsTitle(tag),
+            content: summarizeMemories(memories),
+            examples: memories.slice(0, 3).map(m => m.content),
+        });
+    }
+    return {
+        title: `SOP: ${topic}`,
+        topic,
+        sections,
+        sourceCount: results.length,
+        generatedAt: new Date().toISOString(),
+    };
+}
+/**
+ * Group memories by tags
+ */
+function groupMemoriesByTags(memories) {
+    const groups = {};
+    for (const memory of memories) {
+        for (const tag of memory.tags) {
+            // Skip task/project specific tags
+            if (tag.startsWith('task:') || tag.startsWith('project:')) {
+                continue;
+            }
+            if (!groups[tag]) {
+                groups[tag] = [];
+            }
+            groups[tag].push(memory);
+        }
+    }
+    // Sort by number of memories
+    return Object.fromEntries(Object.entries(groups).sort((a, b) => b[1].length - a[1].length));
+}
+/**
+ * Format tag as section title
+ */
+function formatTagAsTitle(tag) {
+    // Remove prefixes
+    const cleaned = tag.replace(/^(type|source|category):/, '');
+    // Capitalize
+    return cleaned
+        .split(/[-_]/)
+        .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(' ');
+}
+/**
+ * Summarize memories into a paragraph
+ */
+function summarizeMemories(memories) {
+    // Basic summarization (TODO: use LLM for better summary)
+    if (memories.length === 1) {
+        return memories[0].content;
+    }
+    const commonThemes = extractCommonThemes(memories);
+    return `Based on ${memories.length} learnings: ${commonThemes}`;
+}
+/**
+ * Extract common themes from memories
+ */
+function extractCommonThemes(memories) {
+    // Simple word frequency analysis (TODO: use LLM for semantic analysis)
+    const words = {};
+    for (const memory of memories) {
+        const tokens = memory.content
+            .toLowerCase()
+            .split(/\W+/)
+            .filter(w => w.length > 4); // Only words > 4 chars
+        for (const word of tokens) {
+            words[word] = (words[word] || 0) + 1;
+        }
+    }
+    // Get top 5 words
+    const topWords = Object.entries(words)
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 5)
+        .map(([word]) => word);
+    return `Common themes include: ${topWords.join(', ')}`;
+}
+/**
+ * Format SOP as Markdown
+ */
+export function formatSOPAsMarkdown(sop) {
+    let md = `# ${sop.title}\n\n`;
+    md += `**Topic:** ${sop.topic}  \n`;
+    md += `**Generated:** ${new Date(sop.generatedAt).toLocaleString()}  \n`;
+    md += `**Sources:** ${sop.sourceCount} learnings  \n\n`;
+    md += `---\n\n`;
+    for (const section of sop.sections) {
+        md += `## ${section.title}\n\n`;
+        md += `${section.content}\n\n`;
+        if (section.examples && section.examples.length > 0) {
+            md += `### Examples\n\n`;
+            for (const example of section.examples) {
+                md += `- ${example}\n`;
+            }
+            md += `\n`;
+        }
+    }
+    return md;
+}

package/dist/lib/error-hints.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Error Hints System
+ *
+ * Provides helpful hints and references to `husky explain` when users encounter errors.
+ * This makes the CLI more user-friendly by guiding users to relevant documentation.
+ */
+/**
+ * Map of error categories to their corresponding `husky explain` topics
+ */
+export declare enum ExplainTopic {
+    TASK = "task",
+    CONFIG = "config",
+    ROADMAP = "roadmap",
+    CHANGELOG = "changelog",
+    AGENT = "agent"
+}
+/**
+ * Print an error message with an automatic hint based on content
+ */
+export declare function errorWithAutoHint(message: string, exitCode?: number): never;
+/**
+ * Print an error message with a specific hint topic
+ */
+export declare function errorWithHint(message: string, topic: ExplainTopic, customHint?: string, exitCode?: number): never;
+/**
+ * Print an error message with no hint (for errors where no help is available)
+ */
+export declare function errorWithoutHint(message: string, exitCode?: number): never;
+/**
+ * Predefined error helpers for common scenarios
+ */
+export declare const ErrorHelpers: {
+    /**
+     * Error: Task ID not provided
+     */
+    missingTaskId: () => never;
+    /**
+     * Error: API URL not configured
+     */
+    missingApiUrl: () => never;
+    /**
+     * Error: API key not configured
+     */
+    missingApiKey: () => never;
+    /**
+     * Error: Both API URL and key not configured
+     */
+    missingConfig: () => never;
+    /**
+     * Error: Permission denied
+     */
+    permissionDenied: (operation: string) => never;
+    /**
+     * Error: Invalid task status
+     */
+    invalidTaskStatus: (status: string) => never;
+    /**
+     * Error: Task operation failed
+     */
+    taskOperationFailed: (operation: string, reason: string) => never;
+    /**
+     * Error: API request failed
+     */
+    apiRequestFailed: (status: number, message: string) => never;
+};
+/**
+ * Format a warning message with a hint (non-fatal)
+ */
+export declare function warningWithHint(message: string, topic: ExplainTopic, customHint?: string): void;

package/dist/lib/error-hints.js

@@ -0,0 +1,164 @@
+/**
+ * Error Hints System
+ *
+ * Provides helpful hints and references to `husky explain` when users encounter errors.
+ * This makes the CLI more user-friendly by guiding users to relevant documentation.
+ */
+/**
+ * Map of error categories to their corresponding `husky explain` topics
+ */
+export var ExplainTopic;
+(function (ExplainTopic) {
+    ExplainTopic["TASK"] = "task";
+    ExplainTopic["CONFIG"] = "config";
+    ExplainTopic["ROADMAP"] = "roadmap";
+    ExplainTopic["CHANGELOG"] = "changelog";
+    ExplainTopic["AGENT"] = "agent";
+})(ExplainTopic || (ExplainTopic = {}));
+const ERROR_PATTERNS = [
+    {
+        keywords: ["task id", "HUSKY_TASK_ID", "task status", "task complete", "task start"],
+        topic: ExplainTopic.TASK,
+    },
+    {
+        keywords: ["api url", "api key", "not configured", "config set", "authentication"],
+        topic: ExplainTopic.CONFIG,
+    },
+    {
+        keywords: ["roadmap", "phase", "feature"],
+        topic: ExplainTopic.ROADMAP,
+    },
+    {
+        keywords: ["changelog", "version", "commits"],
+        topic: ExplainTopic.CHANGELOG,
+    },
+    {
+        keywords: ["workflow", "agent", "session"],
+        topic: ExplainTopic.AGENT,
+    },
+];
+/**
+ * Detect which explain topic is most relevant based on error message
+ */
+function detectExplainTopic(message) {
+    const lowerMessage = message.toLowerCase();
+    for (const pattern of ERROR_PATTERNS) {
+        if (pattern.keywords.some(keyword => lowerMessage.includes(keyword))) {
+            return pattern.topic;
+        }
+    }
+    return null;
+}
+/**
+ * Format a hint message for a specific explain topic
+ */
+function formatHint(topic, customHint) {
+    if (customHint) {
+        return `\n💡 Hint: ${customHint}\n   Run: husky explain ${topic}`;
+    }
+    const hints = {
+        [ExplainTopic.TASK]: "For task workflow help",
+        [ExplainTopic.CONFIG]: "For configuration help",
+        [ExplainTopic.ROADMAP]: "For roadmap commands help",
+        [ExplainTopic.CHANGELOG]: "For changelog commands help",
+        [ExplainTopic.AGENT]: "For agent workflow examples",
+    };
+    return `\n💡 ${hints[topic]}: husky explain ${topic}`;
+}
+/**
+ * Print an error message with an automatic hint based on content
+ */
+export function errorWithAutoHint(message, exitCode = 1) {
+    console.error(`Error: ${message}`);
+    const topic = detectExplainTopic(message);
+    if (topic) {
+        console.error(formatHint(topic));
+    }
+    process.exit(exitCode);
+}
+/**
+ * Print an error message with a specific hint topic
+ */
+export function errorWithHint(message, topic, customHint, exitCode = 1) {
+    console.error(`Error: ${message}`);
+    console.error(formatHint(topic, customHint));
+    process.exit(exitCode);
+}
+/**
+ * Print an error message with no hint (for errors where no help is available)
+ */
+export function errorWithoutHint(message, exitCode = 1) {
+    console.error(`Error: ${message}`);
+    process.exit(exitCode);
+}
+/**
+ * Predefined error helpers for common scenarios
+ */
+export const ErrorHelpers = {
+    /**
+     * Error: Task ID not provided
+     */
+    missingTaskId: () => {
+        errorWithHint("Task ID required. Use --id or set HUSKY_TASK_ID environment variable.", ExplainTopic.TASK, "Learn about task ID usage and environment variables");
+    },
+    /**
+     * Error: API URL not configured
+     */
+    missingApiUrl: () => {
+        errorWithHint("API URL not configured. Run: husky config set api-url <url>", ExplainTopic.CONFIG, "Learn how to configure the CLI");
+    },
+    /**
+     * Error: API key not configured
+     */
+    missingApiKey: () => {
+        errorWithHint("API key not configured. Run: husky config set api-key <key>", ExplainTopic.CONFIG, "Learn how to configure authentication");
+    },
+    /**
+     * Error: Both API URL and key not configured
+     */
+    missingConfig: () => {
+        errorWithHint("API URL and key required. Run: husky config test", ExplainTopic.CONFIG, "Learn about CLI configuration");
+    },
+    /**
+     * Error: Permission denied
+     */
+    permissionDenied: (operation) => {
+        errorWithAutoHint(`Permission denied: ${operation}`);
+    },
+    /**
+     * Error: Invalid task status
+     */
+    invalidTaskStatus: (status) => {
+        errorWithHint(`Invalid status: ${status}. Valid statuses: backlog, in_progress, review, done`, ExplainTopic.TASK, "See all available task statuses");
+    },
+    /**
+     * Error: Task operation failed
+     */
+    taskOperationFailed: (operation, reason) => {
+        errorWithHint(`Failed to ${operation}: ${reason}`, ExplainTopic.TASK, "Learn about task management");
+    },
+    /**
+     * Error: API request failed
+     */
+    apiRequestFailed: (status, message) => {
+        if (status === 401) {
+            errorWithHint("Authentication failed. Check your API key.", ExplainTopic.CONFIG, "Learn how to configure authentication");
+        }
+        else if (status === 403) {
+            errorWithAutoHint(`Permission denied: ${message}`);
+        }
+        else if (status === 404) {
+            errorWithoutHint(`Resource not found: ${message}`);
+        }
+        else {
+            errorWithAutoHint(`API error (${status}): ${message}`);
+        }
+    },
+};
+/**
+ * Format a warning message with a hint (non-fatal)
+ */
+export function warningWithHint(message, topic, customHint) {
+    console.warn(`⚠ Warning: ${message}`);
+    console.warn(formatHint(topic, customHint).replace("💡", "ℹ️"));
+}

package/dist/lib/permissions.js

@@ -5,6 +5,7 @@
  * Permissions are fetched from the API and cached locally.
  */
 import { getConfig, hasPermission, getRole, fetchAndCacheRole, clearRoleCache } from "../commands/config.js";
+import { ExplainTopic } from "./error-hints.js";
 /**
  * Check if current user has a specific permission.
  * Uses cached permissions from config.
@@ -27,6 +28,7 @@ export function requirePermission(permission) {
         else {
             console.error("Run 'husky config test' to refresh your role and permissions.");
         }
+        console.error(`\n💡 For configuration help: husky explain ${ExplainTopic.CONFIG}`);
         process.exit(1);
     }
 }
@@ -43,6 +45,7 @@ export function requireAnyPermission(permissions) {
         if (config.role) {
             console.error(`Your role (${config.role}) does not have these permissions.`);
         }
+        console.error(`\n💡 For configuration help: husky explain ${ExplainTopic.CONFIG}`);
         process.exit(1);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simonfestl/husky-cli",
-  "version": "1.7.0",
+  "version": "1.9.1",
   "description": "CLI for Huskyv0 Task Orchestration with Claude Agent SDK",
   "type": "module",
   "bin": {
@@ -20,9 +20,14 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-code": "^1.0.0",
+    "@google-cloud/vertexai": "^1.10.0",
+    "@google/generative-ai": "^0.24.1",
     "@inquirer/prompts": "^8.1.0",
     "commander": "^12.1.0",
-    "firebase-admin": "^13.6.0"
+    "firebase-admin": "^13.6.0",
+    "sharp": "^0.34.5",
+    "youtube-transcript": "^1.2.1",
+    "zod": "^4.3.5"
   },
   "devDependencies": {
     "@types/node": "^22",