@codewalla_india/openspec 1.3.0 → 1.3.2

package/dist/comprehension-quiz/providers/local.js

@@ -0,0 +1,53 @@
+/**
+ * Local model provider implementation
+ *
+ * This module implements the local model LLM provider for question generation.
+ * It supports running local models for offline or private question generation.
+ *
+ * @module comprehension-quiz/providers/local
+ */
+import { BaseProvider } from './interface.js';
+/**
+ * Local model provider for question generation
+ *
+ * Requires LOCAL_MODEL_PATH environment variable to be set.
+ */
+export class LocalProvider extends BaseProvider {
+    constructor(config) {
+        super(config);
+    }
+    /**
+     * Validate local model configuration
+     *
+     * @throws Error if model path is missing
+     */
+    validateConfig() {
+        if (!this.config.model) {
+            throw new Error('LOCAL_MODEL_PATH environment variable is required for local provider');
+        }
+    }
+    /**
+     * Generate quiz questions using local model
+     *
+     * @param artifactContent - The content of the artifact to generate questions from
+     * @param questionCount - Number of questions to generate
+     * @param artifactType - Type of artifact (proposal, design, specs, plan, tasks)
+     * @returns Array of generated questions
+     */
+    async generateQuestions(artifactContent, questionCount, artifactType) {
+        // TODO: Implement local model inference
+        // For now, return placeholder questions
+        const questions = [];
+        for (let i = 0; i < questionCount; i++) {
+            questions.push({
+                text: `Sample question ${i + 1} for ${artifactType}`,
+                options: ['Option A', 'Option B', 'Option C'],
+                correctOption: 0,
+                artifactSource: artifactType,
+            });
+        }
+        this.validateQuestions(questions);
+        return questions;
+    }
+}
+//# sourceMappingURL=local.js.map

package/dist/comprehension-quiz/providers/ollama.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Ollama provider implementation
+ *
+ * This module implements the Ollama LLM provider for question generation.
+ * It uses the Ollama API to generate quiz questions from artifact content.
+ *
+ * @module comprehension-quiz/providers/ollama
+ */
+import { BaseProvider } from './interface.js';
+import type { ProviderConfig, Question } from '../types.js';
+/**
+ * Ollama provider for question generation
+ *
+ * Requires OLLAMA_BASE_URL environment variable to be set.
+ */
+export declare class OllamaProvider extends BaseProvider {
+    constructor(config: ProviderConfig);
+    /**
+     * Validate Ollama configuration
+     *
+     * @throws Error if endpoint is missing
+     */
+    validateConfig(): void;
+    /**
+     * Generate quiz questions using Ollama API
+     *
+     * @param artifactContent - The content of the artifact to generate questions from
+     * @param questionCount - Number of questions to generate
+     * @param artifactType - Type of artifact (proposal, design, specs, plan, tasks)
+     * @returns Array of generated questions
+     */
+    generateQuestions(artifactContent: string, questionCount: number, artifactType: 'proposal' | 'design' | 'specs' | 'plan' | 'tasks'): Promise<Question[]>;
+}
+//# sourceMappingURL=ollama.d.ts.map

package/dist/comprehension-quiz/providers/ollama.js

@@ -0,0 +1,53 @@
+/**
+ * Ollama provider implementation
+ *
+ * This module implements the Ollama LLM provider for question generation.
+ * It uses the Ollama API to generate quiz questions from artifact content.
+ *
+ * @module comprehension-quiz/providers/ollama
+ */
+import { BaseProvider } from './interface.js';
+/**
+ * Ollama provider for question generation
+ *
+ * Requires OLLAMA_BASE_URL environment variable to be set.
+ */
+export class OllamaProvider extends BaseProvider {
+    constructor(config) {
+        super(config);
+    }
+    /**
+     * Validate Ollama configuration
+     *
+     * @throws Error if endpoint is missing
+     */
+    validateConfig() {
+        if (!this.config.endpoint) {
+            throw new Error('OLLAMA_BASE_URL environment variable is required for Ollama provider');
+        }
+    }
+    /**
+     * Generate quiz questions using Ollama API
+     *
+     * @param artifactContent - The content of the artifact to generate questions from
+     * @param questionCount - Number of questions to generate
+     * @param artifactType - Type of artifact (proposal, design, specs, plan, tasks)
+     * @returns Array of generated questions
+     */
+    async generateQuestions(artifactContent, questionCount, artifactType) {
+        // TODO: Implement Ollama API call
+        // For now, return placeholder questions
+        const questions = [];
+        for (let i = 0; i < questionCount; i++) {
+            questions.push({
+                text: `Sample question ${i + 1} for ${artifactType}`,
+                options: ['Option A', 'Option B', 'Option C'],
+                correctOption: 0,
+                artifactSource: artifactType,
+            });
+        }
+        this.validateQuestions(questions);
+        return questions;
+    }
+}
+//# sourceMappingURL=ollama.js.map

package/dist/comprehension-quiz/providers/openai.d.ts

@@ -0,0 +1,34 @@
+/**
+ * OpenAI provider implementation
+ *
+ * This module implements the OpenAI LLM provider for question generation.
+ * It uses the OpenAI API to generate quiz questions from artifact content.
+ *
+ * @module comprehension-quiz/providers/openai
+ */
+import { BaseProvider } from './interface.js';
+import type { ProviderConfig, Question } from '../types.js';
+/**
+ * OpenAI provider for question generation
+ *
+ * Requires OPENAI_API_KEY environment variable to be set.
+ */
+export declare class OpenAIProvider extends BaseProvider {
+    constructor(config: ProviderConfig);
+    /**
+     * Validate OpenAI configuration
+     *
+     * @throws Error if API key is missing
+     */
+    validateConfig(): void;
+    /**
+     * Generate quiz questions using OpenAI API
+     *
+     * @param artifactContent - The content of the artifact to generate questions from
+     * @param questionCount - Number of questions to generate
+     * @param artifactType - Type of artifact (proposal, design, specs, plan, tasks)
+     * @returns Array of generated questions
+     */
+    generateQuestions(artifactContent: string, questionCount: number, artifactType: 'proposal' | 'design' | 'specs' | 'plan' | 'tasks'): Promise<Question[]>;
+}
+//# sourceMappingURL=openai.d.ts.map

package/dist/comprehension-quiz/providers/openai.js

@@ -0,0 +1,53 @@
+/**
+ * OpenAI provider implementation
+ *
+ * This module implements the OpenAI LLM provider for question generation.
+ * It uses the OpenAI API to generate quiz questions from artifact content.
+ *
+ * @module comprehension-quiz/providers/openai
+ */
+import { BaseProvider } from './interface.js';
+/**
+ * OpenAI provider for question generation
+ *
+ * Requires OPENAI_API_KEY environment variable to be set.
+ */
+export class OpenAIProvider extends BaseProvider {
+    constructor(config) {
+        super(config);
+    }
+    /**
+     * Validate OpenAI configuration
+     *
+     * @throws Error if API key is missing
+     */
+    validateConfig() {
+        if (!this.config.apiKey) {
+            throw new Error('OPENAI_API_KEY environment variable is required for OpenAI provider');
+        }
+    }
+    /**
+     * Generate quiz questions using OpenAI API
+     *
+     * @param artifactContent - The content of the artifact to generate questions from
+     * @param questionCount - Number of questions to generate
+     * @param artifactType - Type of artifact (proposal, design, specs, plan, tasks)
+     * @returns Array of generated questions
+     */
+    async generateQuestions(artifactContent, questionCount, artifactType) {
+        // TODO: Implement OpenAI API call
+        // For now, return placeholder questions
+        const questions = [];
+        for (let i = 0; i < questionCount; i++) {
+            questions.push({
+                text: `Sample question ${i + 1} for ${artifactType}`,
+                options: ['Option A', 'Option B', 'Option C'],
+                correctOption: 0,
+                artifactSource: artifactType,
+            });
+        }
+        this.validateQuestions(questions);
+        return questions;
+    }
+}
+//# sourceMappingURL=openai.js.map

package/dist/comprehension-quiz/question-generator.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Question generator for quiz questions
+ *
+ * This module handles reading artifact content and generating quiz questions
+ * using LLM providers. It includes logic for question count scaling based on
+ * artifact size and proportional question allocation across artifact types.
+ *
+ * @module comprehension-quiz/question-generator
+ */
+import type { Question, LLMProvider } from './types.js';
+/**
+ * Determine question count based on artifact size
+ *
+ * @param totalSize - Total size of all artifacts in bytes
+ * @returns Number of questions to generate (5, 7, or 10)
+ */
+export declare function getQuestionCount(totalSize: number): number;
+/**
+ * Calculate question allocation per artifact type
+ *
+ * Distributes questions proportionally to artifact size, ensuring at least
+ * one question per artifact type if it has content.
+ *
+ * @param totalQuestions - Total number of questions to generate
+ * @param artifactSizes - Size of each artifact type in bytes
+ * @returns Object with question count per artifact type
+ */
+export declare function calculateQuestionAllocation(totalQuestions: number, artifactSizes: {
+    proposal: number;
+    design: number;
+    specs: number;
+    plan: number;
+    tasks: number;
+}): {
+    proposal: number;
+    design: number;
+    specs: number;
+    plan: number;
+    tasks: number;
+};
+/**
+ * Generate questions for a specific artifact type
+ *
+ * @param artifactContent - Content of the artifact
+ * @param artifactType - Type of artifact
+ * @param questionCount - Number of questions to generate
+ * @param provider - LLM provider to use
+ * @returns Array of generated questions
+ */
+export declare function generateQuestionsForArtifact(artifactContent: string, artifactType: 'proposal' | 'design' | 'specs' | 'plan' | 'tasks', questionCount: number, provider: LLMProvider): Promise<Question[]>;
+/**
+ * Generate complete quiz question set for all artifacts
+ *
+ * Reads all artifact files, calculates question allocation, and generates
+ * questions for each artifact type using the provided or fallback LLM provider.
+ *
+ * @param artifactPaths - Object mapping artifact types to file paths
+ * @param totalQuestions - Total number of questions to generate
+ * @param provider - LLM provider to use (optional, uses fallback if not provided)
+ * @returns Array of all generated questions
+ */
+export declare function generateQuizQuestions(artifactPaths: {
+    proposal?: string;
+    design?: string;
+    specs?: string;
+    plan?: string;
+    tasks?: string;
+}, totalQuestions: number, provider?: LLMProvider): Promise<Question[]>;
+//# sourceMappingURL=question-generator.d.ts.map

package/dist/comprehension-quiz/question-generator.js

@@ -0,0 +1,141 @@
+/**
+ * Question generator for quiz questions
+ *
+ * This module handles reading artifact content and generating quiz questions
+ * using LLM providers. It includes logic for question count scaling based on
+ * artifact size and proportional question allocation across artifact types.
+ *
+ * @module comprehension-quiz/question-generator
+ */
+import { createProviderWithFallback } from './providers/factory.js';
+/**
+ * Read artifact content from file
+ *
+ * @param filePath - Path to the artifact file
+ * @returns File content as string
+ */
+async function readArtifactContent(filePath) {
+    const { promises: fs } = await import('fs');
+    try {
+        return await fs.readFile(filePath, 'utf-8');
+    }
+    catch (error) {
+        throw new Error(`Failed to read artifact file ${filePath}: ${error}`);
+    }
+}
+/**
+ * Determine question count based on artifact size
+ *
+ * @param totalSize - Total size of all artifacts in bytes
+ * @returns Number of questions to generate (5, 7, or 10)
+ */
+export function getQuestionCount(totalSize) {
+    if (totalSize < 2048) {
+        return 5; // < 2KB
+    }
+    else if (totalSize < 10240) {
+        return 7; // 2-10KB
+    }
+    else {
+        return 10; // > 10KB
+    }
+}
+/**
+ * Calculate question allocation per artifact type
+ *
+ * Distributes questions proportionally to artifact size, ensuring at least
+ * one question per artifact type if it has content.
+ *
+ * @param totalQuestions - Total number of questions to generate
+ * @param artifactSizes - Size of each artifact type in bytes
+ * @returns Object with question count per artifact type
+ */
+export function calculateQuestionAllocation(totalQuestions, artifactSizes) {
+    const totalSize = Object.values(artifactSizes).reduce((sum, size) => sum + size, 0);
+    const allocation = {
+        proposal: 0,
+        design: 0,
+        specs: 0,
+        plan: 0,
+        tasks: 0,
+    };
+    // Allocate questions proportionally to artifact size
+    let allocated = 0;
+    for (const [artifactType, size] of Object.entries(artifactSizes)) {
+        const proportion = size / totalSize;
+        const count = Math.round(proportion * totalQuestions);
+        allocation[artifactType] = count;
+        allocated += count;
+    }
+    // Ensure at least 1 question per artifact type if it has content
+    for (const [artifactType, size] of Object.entries(artifactSizes)) {
+        if (size > 0 && allocation[artifactType] === 0 && allocated < totalQuestions) {
+            allocation[artifactType] = 1;
+            allocated += 1;
+        }
+    }
+    // Adjust to match totalQuestions exactly
+    const currentTotal = Object.values(allocation).reduce((sum, count) => sum + count, 0);
+    if (currentTotal !== totalQuestions) {
+        const diff = totalQuestions - currentTotal;
+        // Add remaining questions to the largest artifact
+        const largestArtifact = Object.entries(artifactSizes).sort((a, b) => b[1] - a[1])[0][0];
+        allocation[largestArtifact] += diff;
+    }
+    return allocation;
+}
+/**
+ * Generate questions for a specific artifact type
+ *
+ * @param artifactContent - Content of the artifact
+ * @param artifactType - Type of artifact
+ * @param questionCount - Number of questions to generate
+ * @param provider - LLM provider to use
+ * @returns Array of generated questions
+ */
+export async function generateQuestionsForArtifact(artifactContent, artifactType, questionCount, provider) {
+    return provider.generateQuestions(artifactContent, questionCount, artifactType);
+}
+/**
+ * Generate complete quiz question set for all artifacts
+ *
+ * Reads all artifact files, calculates question allocation, and generates
+ * questions for each artifact type using the provided or fallback LLM provider.
+ *
+ * @param artifactPaths - Object mapping artifact types to file paths
+ * @param totalQuestions - Total number of questions to generate
+ * @param provider - LLM provider to use (optional, uses fallback if not provided)
+ * @returns Array of all generated questions
+ */
+export async function generateQuizQuestions(artifactPaths, totalQuestions, provider) {
+    // Use fallback provider if not provided
+    const llmProvider = provider || await createProviderWithFallback();
+    // Read all artifact contents and calculate sizes
+    const artifactContents = {};
+    const artifactSizes = {
+        proposal: 0,
+        design: 0,
+        specs: 0,
+        plan: 0,
+        tasks: 0,
+    };
+    for (const [artifactType, filePath] of Object.entries(artifactPaths)) {
+        if (filePath) {
+            const content = await readArtifactContent(filePath);
+            artifactContents[artifactType] = content;
+            artifactSizes[artifactType] = content.length;
+        }
+    }
+    // Calculate question allocation
+    const allocation = calculateQuestionAllocation(totalQuestions, artifactSizes);
+    // Generate questions for each artifact type
+    const allQuestions = [];
+    for (const [artifactType, count] of Object.entries(allocation)) {
+        if (count > 0 && artifactContents[artifactType]) {
+            const questions = await generateQuestionsForArtifact(artifactContents[artifactType], artifactType, count, llmProvider);
+            allQuestions.push(...questions);
+        }
+    }
+    return allQuestions;
+}
+//# sourceMappingURL=question-generator.js.map

package/dist/comprehension-quiz/quiz-executor.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Quiz executor with state machine and CLI interaction
+ *
+ * This module implements the quiz execution engine with a strict state machine
+ * and timing constraints to enforce human-only participation. It handles question
+ * presentation, answer collection, timing validation, and feedback display.
+ *
+ * @module comprehension-quiz/quiz-executor
+ */
+import type { Question, QuizResult } from './types.js';
+/**
+ * Quiz executor class
+ *
+ * Manages the quiz state machine and CLI interaction. Enforces timing
+ * constraints (4-second wait before accepting input, 2-second minimum answer time)
+ * to prevent AI agents from programmatically answering questions.
+ */
+export declare class QuizExecutor {
+    private state;
+    private currentQuestionIndex;
+    private questions;
+    private answers;
+    private questionDisplayedAt;
+    private answerReceivedAt;
+    private changeName;
+    private attemptNumber;
+    /**
+     * Execute quiz with given questions
+     *
+     * @param questions - Array of questions to ask
+     * @param changeName - Name of the change being tested
+     * @returns Quiz result with score and pass/fail status
+     */
+    executeQuiz(questions: Question[], changeName: string): Promise<QuizResult>;
+    /**
+     * Transition to a new state
+     *
+     * @param newState - New state to transition to
+     */
+    private transitionTo;
+    /**
+     * Ask a question to the user
+     *
+     * @param questionIndex - Index of the question to ask
+     */
+    private askQuestion;
+    /**
+     * Wait for user answer with timing constraints
+     *
+     * Enforces a minimum 2-second wait time after question display before
+     * accepting input to prevent automated answering.
+     *
+     * @returns User's answer (1, 2, or 3), or -1 if invalid/too early
+     */
+    private waitForAnswer;
+    /**
+     * Show feedback on the answer
+     *
+     * @param questionIndex - Index of the question
+     * @param answer - User's answer
+     */
+    private showFeedback;
+    /**
+     * Calculate quiz result
+     *
+     * @returns Quiz result with score and pass/fail status
+     */
+    private calculateResult;
+}
+//# sourceMappingURL=quiz-executor.d.ts.map

package/dist/comprehension-quiz/quiz-executor.js

@@ -0,0 +1,165 @@
+/**
+ * Quiz executor with state machine and CLI interaction
+ *
+ * This module implements the quiz execution engine with a strict state machine
+ * and timing constraints to enforce human-only participation. It handles question
+ * presentation, answer collection, timing validation, and feedback display.
+ *
+ * @module comprehension-quiz/quiz-executor
+ */
+import * as readline from 'readline';
+import { trackComprehensionAttempt, trackComprehensionCompletion, trackApplyReady } from '../telemetry/index.js';
+import { getPassRecord } from './pass-record.js';
+/**
+ * Quiz executor class
+ *
+ * Manages the quiz state machine and CLI interaction. Enforces timing
+ * constraints (4-second wait before accepting input, 2-second minimum answer time)
+ * to prevent AI agents from programmatically answering questions.
+ */
+export class QuizExecutor {
+    state = 'START';
+    currentQuestionIndex = 0;
+    questions = [];
+    answers = [];
+    questionDisplayedAt = 0;
+    answerReceivedAt = 0;
+    changeName = '';
+    attemptNumber = 1;
+    /**
+     * Execute quiz with given questions
+     *
+     * @param questions - Array of questions to ask
+     * @param changeName - Name of the change being tested
+     * @returns Quiz result with score and pass/fail status
+     */
+    async executeQuiz(questions, changeName) {
+        this.questions = questions;
+        this.changeName = changeName;
+        this.currentQuestionIndex = 0;
+        this.answers = [];
+        this.state = 'START';
+        // Track attempt number from existing pass record
+        const existingRecord = await getPassRecord(changeName);
+        this.attemptNumber = existingRecord ? existingRecord.attemptCount + 1 : 1;
+        // Track attempt start
+        await trackComprehensionAttempt(changeName, this.attemptNumber);
+        // Start the quiz
+        await this.transitionTo('WAITING_FOR_QUESTION_1');
+        for (let i = 0; i < questions.length; i++) {
+            await this.askQuestion(i);
+            const answer = await this.waitForAnswer();
+            this.answers.push(answer);
+            await this.showFeedback(i, answer);
+            if (i < questions.length - 1) {
+                await this.transitionTo(`WAITING_FOR_QUESTION_${i + 2}`);
+            }
+        }
+        await this.transitionTo('DONE');
+        const result = this.calculateResult();
+        // Track completion
+        await trackComprehensionCompletion(changeName, result.scorePercent, result.passed ? 'pass' : 'fail', this.attemptNumber);
+        // If passed, emit apply_ready milestone
+        if (result.passed) {
+            await trackApplyReady(changeName);
+        }
+        return result;
+    }
+    /**
+     * Transition to a new state
+     *
+     * @param newState - New state to transition to
+     */
+    async transitionTo(newState) {
+        this.state = newState;
+    }
+    /**
+     * Ask a question to the user
+     *
+     * @param questionIndex - Index of the question to ask
+     */
+    async askQuestion(questionIndex) {
+        const question = this.questions[questionIndex];
+        console.log(`\nQuestion ${questionIndex + 1}/${this.questions.length}:`);
+        console.log(question.text);
+        console.log('');
+        console.log('1)', question.options[0]);
+        console.log('2)', question.options[1]);
+        console.log('3)', question.options[2]);
+        console.log('');
+        this.questionDisplayedAt = Date.now();
+    }
+    /**
+     * Wait for user answer with timing constraints
+     *
+     * Enforces a minimum 2-second wait time after question display before
+     * accepting input to prevent automated answering.
+     *
+     * @returns User's answer (1, 2, or 3), or -1 if invalid/too early
+     */
+    async waitForAnswer() {
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        const answer = await new Promise((resolve) => {
+            rl.question('', (answer) => {
+                rl.close();
+                const trimmed = answer.trim();
+                // Check if answer was submitted too early (less than 2 seconds after question display)
+                const timeSinceDisplay = Date.now() - this.questionDisplayedAt;
+                if (timeSinceDisplay < 2000) {
+                    console.log('Answer submitted too early. Please wait at least 2 seconds before answering.');
+                    resolve(-1);
+                    return;
+                }
+                // Validate input
+                if (trimmed === '1' || trimmed === '2' || trimmed === '3') {
+                    resolve(parseInt(trimmed, 10));
+                }
+                else {
+                    console.log('Answer this question to continue.');
+                    resolve(-1);
+                }
+            });
+        });
+        return answer;
+    }
+    /**
+     * Show feedback on the answer
+     *
+     * @param questionIndex - Index of the question
+     * @param answer - User's answer
+     */
+    async showFeedback(questionIndex, answer) {
+        const question = this.questions[questionIndex];
+        const isCorrect = answer === question.correctOption + 1;
+        if (isCorrect) {
+            console.log('✓ Correct');
+        }
+        else {
+            console.log('✗ Incorrect');
+            console.log(`The correct answer was ${question.correctOption + 1}`);
+        }
+        // Clear terminal screen
+        console.clear();
+    }
+    /**
+     * Calculate quiz result
+     *
+     * @returns Quiz result with score and pass/fail status
+     */
+    calculateResult() {
+        const correct = this.answers.filter((answer, index) => answer === this.questions[index].correctOption + 1).length;
+        const total = this.questions.length;
+        const scorePercent = Math.round((correct / total) * 100);
+        return {
+            correct,
+            total,
+            scorePercent,
+            passed: scorePercent >= 80,
+            attemptNumber: 1, // TODO: Track attempt count
+        };
+    }
+}
+//# sourceMappingURL=quiz-executor.js.map