clavix 2.3.0 → 2.4.0

package/dist/core 2/question-engine.d.ts

@@ -0,0 +1,167 @@
+/**
+ * QuestionEngine - Manages Socratic questioning flows for PRD generation
+ *
+ * This class handles:
+ * - Loading question templates
+ * - Sequential and conditional question flows
+ * - Answer collection and validation
+ * - Progress tracking
+ */
+/**
+ * Type of question input
+ */
+export type QuestionType = 'text' | 'list' | 'confirm';
+/**
+ * A single question in the flow
+ */
+export interface Question {
+    id: string;
+    text: string;
+    type: QuestionType;
+    required: boolean;
+    choices?: string[];
+    default?: string | boolean;
+    validate?: (answer: string) => boolean | string;
+    condition?: (answers: Record<string, Answer>) => boolean;
+}
+/**
+ * Answer to a question
+ */
+export type Answer = string | boolean | string[];
+/**
+ * Collection of answers keyed by question ID
+ */
+export interface Answers {
+    [questionId: string]: Answer;
+}
+/**
+ * Question flow configuration
+ */
+export interface QuestionFlow {
+    name: string;
+    description: string;
+    questions: Question[];
+}
+/**
+ * Progress information for multi-question flows
+ */
+export interface QuestionProgress {
+    current: number;
+    total: number;
+    percentage: number;
+}
+/**
+ * QuestionEngine class
+ *
+ * Manages the flow of questions, answer collection, and validation
+ */
+export declare class QuestionEngine {
+    private currentFlow;
+    private answers;
+    private currentQuestionIndex;
+    /**
+     * Load a question flow from a template file
+     *
+     * @param templatePath - Path to the question template
+     * @returns The loaded question flow
+     */
+    loadFlow(templatePath: string): Promise<QuestionFlow>;
+    /**
+     * Parse a question template into a QuestionFlow
+     *
+     * Template format:
+     * ```markdown
+     * # Flow Name
+     *
+     * Flow description
+     *
+     * ## Question 1
+     *
+     * **text:** What problem are you solving?
+     * **type:** text
+     * **required:** true
+     * **validation:** minLength:10
+     *
+     * ## Question 2
+     *
+     * **text:** Select your technology stack
+     * **type:** list
+     * **choices:** React, Vue, Angular, Other
+     * ```
+     *
+     * @param template - Template content
+     * @returns Parsed QuestionFlow
+     */
+    private parseTemplate;
+    /**
+     * Parse a single metadata field for a question
+     */
+    private parseQuestionMetadata;
+    /**
+     * Finalize a question by setting defaults and generating ID
+     */
+    private finalizeQuestion;
+    /**
+     * Create a validation function from a validation string
+     *
+     * Supported formats:
+     * - minLength:10 - Minimum length
+     * - maxLength:100 - Maximum length
+     * - pattern:^[a-z]+$ - Regex pattern
+     * - email - Email validation
+     * - url - URL validation
+     */
+    private createValidator;
+    /**
+     * Create a condition function from a condition string
+     *
+     * Supported formats:
+     * - q1=true - Question 1 answer equals true
+     * - q2=JWT - Question 2 answer equals "JWT"
+     * - q3!=None - Question 3 answer not equals "None"
+     */
+    private createCondition;
+    /**
+     * Get the next question in the flow
+     *
+     * @returns The next question, or null if flow is complete
+     */
+    getNextQuestion(): Question | null;
+    /**
+     * Submit an answer to the current question
+     *
+     * @param questionId - ID of the question being answered
+     * @param answer - The answer
+     * @returns Validation result (true if valid, error message if invalid)
+     */
+    submitAnswer(questionId: string, answer: Answer): boolean | string;
+    /**
+     * Get all collected answers
+     *
+     * @returns All answers collected so far
+     */
+    getAnswers(): Answers;
+    /**
+     * Get current progress through the question flow
+     *
+     * @returns Progress information
+     */
+    getProgress(): QuestionProgress;
+    /**
+     * Check if the question flow is complete
+     *
+     * @returns True if all required questions are answered
+     */
+    isComplete(): boolean;
+    /**
+     * Reset the question flow
+     */
+    reset(): void;
+    /**
+     * Get the current question flow
+     *
+     * @returns The loaded question flow, or null if none loaded
+     */
+    getCurrentFlow(): QuestionFlow | null;
+}
+//# sourceMappingURL=question-engine.d.ts.map

package/dist/core 2/question-engine.js

@@ -0,0 +1,395 @@
+"use strict";
+/**
+ * QuestionEngine - Manages Socratic questioning flows for PRD generation
+ *
+ * This class handles:
+ * - Loading question templates
+ * - Sequential and conditional question flows
+ * - Answer collection and validation
+ * - Progress tracking
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QuestionEngine = void 0;
+const fs = __importStar(require("fs-extra"));
+const path = __importStar(require("path"));
+/**
+ * QuestionEngine class
+ *
+ * Manages the flow of questions, answer collection, and validation
+ */
+class QuestionEngine {
+    constructor() {
+        this.currentFlow = null;
+        this.answers = {};
+        this.currentQuestionIndex = 0;
+    }
+    /**
+     * Load a question flow from a template file
+     *
+     * @param templatePath - Path to the question template
+     * @returns The loaded question flow
+     */
+    async loadFlow(templatePath) {
+        const fullPath = path.resolve(templatePath);
+        if (!await fs.pathExists(fullPath)) {
+            throw new Error(`Question template not found: ${templatePath}`);
+        }
+        const content = await fs.readFile(fullPath, 'utf-8');
+        const flow = this.parseTemplate(content);
+        this.currentFlow = flow;
+        this.answers = {};
+        this.currentQuestionIndex = 0;
+        return flow;
+    }
+    /**
+     * Parse a question template into a QuestionFlow
+     *
+     * Template format:
+     * ```markdown
+     * # Flow Name
+     *
+     * Flow description
+     *
+     * ## Question 1
+     *
+     * **text:** What problem are you solving?
+     * **type:** text
+     * **required:** true
+     * **validation:** minLength:10
+     *
+     * ## Question 2
+     *
+     * **text:** Select your technology stack
+     * **type:** list
+     * **choices:** React, Vue, Angular, Other
+     * ```
+     *
+     * @param template - Template content
+     * @returns Parsed QuestionFlow
+     */
+    parseTemplate(template) {
+        const lines = template.split('\n');
+        const questions = [];
+        let name = 'Default Flow';
+        let description = '';
+        let currentQuestion = null;
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i].trim();
+            // Skip empty lines
+            if (!line) {
+                continue;
+            }
+            // Extract flow name from first h1
+            if (line.startsWith('# ') && name === 'Default Flow') {
+                name = line.substring(2).trim();
+                continue;
+            }
+            // Extract description (first non-heading paragraph)
+            if (line && !line.startsWith('#') && !line.startsWith('**') && !description) {
+                description = line;
+                continue;
+            }
+            // Start new question on h2
+            if (line.startsWith('## ')) {
+                // Save previous question if exists
+                if (currentQuestion && currentQuestion.text) {
+                    questions.push(this.finalizeQuestion(currentQuestion, questions.length));
+                }
+                // Start new question
+                currentQuestion = {};
+                continue;
+            }
+            // Parse question metadata: **key:** value
+            const metadataMatch = line.match(/^\*\*(\w+):\*\*\s*(.+)$/);
+            if (metadataMatch && currentQuestion) {
+                const [, key, value] = metadataMatch;
+                this.parseQuestionMetadata(currentQuestion, key, value);
+            }
+        }
+        // Save last question
+        if (currentQuestion && currentQuestion.text) {
+            questions.push(this.finalizeQuestion(currentQuestion, questions.length));
+        }
+        return { name, description, questions };
+    }
+    /**
+     * Parse a single metadata field for a question
+     */
+    parseQuestionMetadata(question, key, value) {
+        switch (key.toLowerCase()) {
+            case 'text':
+                question.text = value;
+                break;
+            case 'type':
+                if (value === 'text' || value === 'list' || value === 'confirm') {
+                    question.type = value;
+                }
+                break;
+            case 'required':
+                question.required = value.toLowerCase() === 'true';
+                break;
+            case 'choices':
+                question.choices = value.split(',').map((c) => c.trim());
+                break;
+            case 'default':
+                if (question.type === 'confirm') {
+                    question.default = value.toLowerCase() === 'true';
+                }
+                else {
+                    question.default = value;
+                }
+                break;
+            case 'validation':
+                question.validate = this.createValidator(value);
+                break;
+            case 'condition':
+                question.condition = this.createCondition(value);
+                break;
+        }
+    }
+    /**
+     * Finalize a question by setting defaults and generating ID
+     */
+    finalizeQuestion(partial, index) {
+        return {
+            id: `q${index + 1}`,
+            text: partial.text || '',
+            type: partial.type || 'text',
+            required: partial.required !== undefined ? partial.required : true,
+            choices: partial.choices,
+            default: partial.default,
+            validate: partial.validate,
+            condition: partial.condition,
+        };
+    }
+    /**
+     * Create a validation function from a validation string
+     *
+     * Supported formats:
+     * - minLength:10 - Minimum length
+     * - maxLength:100 - Maximum length
+     * - pattern:^[a-z]+$ - Regex pattern
+     * - email - Email validation
+     * - url - URL validation
+     */
+    createValidator(validationStr) {
+        const parts = validationStr.split(':');
+        const type = parts[0].toLowerCase();
+        const param = parts[1];
+        return (answer) => {
+            switch (type) {
+                case 'minlength':
+                    if (answer.length < parseInt(param, 10)) {
+                        return `Minimum length is ${param} characters`;
+                    }
+                    break;
+                case 'maxlength':
+                    if (answer.length > parseInt(param, 10)) {
+                        return `Maximum length is ${param} characters`;
+                    }
+                    break;
+                case 'pattern':
+                    if (!new RegExp(param).test(answer)) {
+                        return 'Answer does not match required format';
+                    }
+                    break;
+                case 'email':
+                    if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(answer)) {
+                        return 'Please enter a valid email address';
+                    }
+                    break;
+                case 'url':
+                    try {
+                        new URL(answer);
+                    }
+                    catch {
+                        return 'Please enter a valid URL';
+                    }
+                    break;
+            }
+            return true;
+        };
+    }
+    /**
+     * Create a condition function from a condition string
+     *
+     * Supported formats:
+     * - q1=true - Question 1 answer equals true
+     * - q2=JWT - Question 2 answer equals "JWT"
+     * - q3!=None - Question 3 answer not equals "None"
+     */
+    createCondition(conditionStr) {
+        const match = conditionStr.match(/^(\w+)\s*(=|!=)\s*(.+)$/);
+        if (!match) {
+            return () => true;
+        }
+        const [, questionId, operator, expectedValue] = match;
+        return (answers) => {
+            const actualValue = answers[questionId];
+            // Convert expected value to proper type
+            let expected = expectedValue;
+            if (expectedValue.toLowerCase() === 'true') {
+                expected = true;
+            }
+            else if (expectedValue.toLowerCase() === 'false') {
+                expected = false;
+            }
+            if (operator === '=') {
+                return actualValue === expected;
+            }
+            else {
+                return actualValue !== expected;
+            }
+        };
+    }
+    /**
+     * Get the next question in the flow
+     *
+     * @returns The next question, or null if flow is complete
+     */
+    getNextQuestion() {
+        if (!this.currentFlow) {
+            throw new Error('No question flow loaded');
+        }
+        // Find the next unanswered question that meets its condition
+        while (this.currentQuestionIndex < this.currentFlow.questions.length) {
+            const question = this.currentFlow.questions[this.currentQuestionIndex];
+            // Skip if already answered
+            if (question.id in this.answers) {
+                this.currentQuestionIndex++;
+                continue;
+            }
+            // Check if question condition is met (if it has one)
+            if (question.condition && !question.condition(this.answers)) {
+                this.currentQuestionIndex++;
+                continue;
+            }
+            return question;
+        }
+        return null;
+    }
+    /**
+     * Submit an answer to the current question
+     *
+     * @param questionId - ID of the question being answered
+     * @param answer - The answer
+     * @returns Validation result (true if valid, error message if invalid)
+     */
+    submitAnswer(questionId, answer) {
+        if (!this.currentFlow) {
+            throw new Error('No question flow loaded');
+        }
+        const question = this.currentFlow.questions.find((q) => q.id === questionId);
+        if (!question) {
+            throw new Error(`Question not found: ${questionId}`);
+        }
+        // Validate required fields (but allow false for boolean answers)
+        if (question.required && (answer === '' || answer === null || answer === undefined)) {
+            return 'This question is required';
+        }
+        // Run custom validation if provided
+        if (question.validate) {
+            const validationResult = question.validate(String(answer));
+            if (validationResult !== true) {
+                return validationResult;
+            }
+        }
+        // Store the answer
+        this.answers[questionId] = answer;
+        this.currentQuestionIndex++;
+        return true;
+    }
+    /**
+     * Get all collected answers
+     *
+     * @returns All answers collected so far
+     */
+    getAnswers() {
+        return { ...this.answers };
+    }
+    /**
+     * Get current progress through the question flow
+     *
+     * @returns Progress information
+     */
+    getProgress() {
+        if (!this.currentFlow) {
+            return { current: 0, total: 0, percentage: 0 };
+        }
+        const total = this.currentFlow.questions.length;
+        const current = Object.keys(this.answers).length;
+        const percentage = total > 0 ? Math.round((current / total) * 100) : 0;
+        return { current, total, percentage };
+    }
+    /**
+     * Check if the question flow is complete
+     *
+     * @returns True if all required questions are answered
+     */
+    isComplete() {
+        if (!this.currentFlow) {
+            return false;
+        }
+        // Check if all required questions have answers
+        for (const question of this.currentFlow.questions) {
+            // Skip if condition not met
+            if (question.condition && !question.condition(this.answers)) {
+                continue;
+            }
+            if (question.required && !(question.id in this.answers)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Reset the question flow
+     */
+    reset() {
+        this.answers = {};
+        this.currentQuestionIndex = 0;
+    }
+    /**
+     * Get the current question flow
+     *
+     * @returns The loaded question flow, or null if none loaded
+     */
+    getCurrentFlow() {
+        return this.currentFlow;
+    }
+}
+exports.QuestionEngine = QuestionEngine;
+//# sourceMappingURL=question-engine.js.map

package/dist/core 2/session-manager.d.ts

@@ -0,0 +1,139 @@
+/**
+ * SessionManager - Manages conversational sessions for clavix start/summarize
+ *
+ * This class handles:
+ * - Session creation with unique IDs
+ * - Message tracking and storage
+ * - Session file persistence (JSON format)
+ * - Session listing, filtering, and search
+ * - CRUD operations for sessions
+ *
+ * Sessions are stored in `.clavix/sessions/` as JSON files:
+ * `.clavix/sessions/{session-id}.json`
+ */
+import { Session, SessionMetadata, SessionFilter } from '../types/session';
+/**
+ * Options for creating a new session
+ */
+export interface CreateSessionOptions {
+    projectName?: string;
+    agent?: string;
+    description?: string;
+    tags?: string[];
+}
+/**
+ * SessionManager class
+ *
+ * Manages all session-related operations including creation, storage,
+ * retrieval, listing, and search functionality.
+ */
+export declare class SessionManager {
+    private readonly sessionsDir;
+    private readonly defaultSessionsDir;
+    constructor(sessionsDir?: string);
+    /**
+     * Create a new session
+     *
+     * @param options - Session creation options
+     * @returns The created session
+     */
+    createSession(options?: CreateSessionOptions): Promise<Session>;
+    /**
+     * Get a session by ID
+     *
+     * @param sessionId - The session ID
+     * @returns The session, or null if not found
+     */
+    getSession(sessionId: string): Promise<Session | null>;
+    /**
+     * Save a session to disk
+     *
+     * @param session - The session to save
+     */
+    saveSession(session: Session): Promise<void>;
+    /**
+     * Update a session
+     *
+     * @param sessionId - The session ID
+     * @param updates - Partial session updates
+     * @returns The updated session, or null if not found
+     */
+    updateSession(sessionId: string, updates: Partial<Omit<Session, 'id' | 'created'>>): Promise<Session | null>;
+    /**
+     * Delete a session
+     *
+     * @param sessionId - The session ID
+     * @returns True if deleted, false if not found
+     */
+    deleteSession(sessionId: string): Promise<boolean>;
+    /**
+     * Add a message to a session
+     *
+     * @param sessionId - The session ID
+     * @param role - Message role (user or assistant)
+     * @param content - Message content
+     * @returns The updated session, or null if session not found
+     */
+    addMessage(sessionId: string, role: 'user' | 'assistant', content: string): Promise<Session | null>;
+    /**
+     * List all sessions with optional filtering
+     *
+     * @param filter - Optional filter criteria
+     * @returns Array of session metadata
+     */
+    listSessions(filter?: SessionFilter): Promise<SessionMetadata[]>;
+    /**
+     * Search sessions by keyword
+     *
+     * Searches in project name, description, tags, and message content
+     *
+     * @param keyword - Search keyword
+     * @returns Array of matching session metadata
+     */
+    searchSessions(keyword: string): Promise<SessionMetadata[]>;
+    /**
+     * Get the most recent active session
+     *
+     * @returns The active session, or null if none exists
+     */
+    getActiveSession(): Promise<Session | null>;
+    /**
+     * Mark a session as completed
+     *
+     * @param sessionId - The session ID
+     * @returns The updated session, or null if not found
+     */
+    completeSession(sessionId: string): Promise<Session | null>;
+    /**
+     * Mark a session as archived
+     *
+     * @param sessionId - The session ID
+     * @returns The updated session, or null if not found
+     */
+    archiveSession(sessionId: string): Promise<Session | null>;
+    /**
+     * Get the path to a session file
+     */
+    private getSessionPath;
+    /**
+     * Generate a default project name based on timestamp
+     */
+    private generateDefaultProjectName;
+    /**
+     * Serialize a session for file storage
+     */
+    private serializeSession;
+    /**
+     * Deserialize a session from file storage
+     */
+    private deserializeSession;
+    /**
+     * Extract metadata from a serialized session
+     */
+    private extractMetadata;
+    /**
+     * Check if session metadata matches filter criteria
+     */
+    private matchesFilter;
+}
+//# sourceMappingURL=session-manager.d.ts.map