@codewalla_india/openspec 1.3.1 → 1.3.3

package/dist/comprehension-quiz/index.js

@@ -0,0 +1,47 @@
+/**
+ * Comprehension quiz system main entry point
+ *
+ * This module provides the main entry point for the comprehension quiz system,
+ * which enforces that developers read and understand change artifacts before
+ * implementation. The quiz blocks the `/opsx:apply` command until passed with a score
+ * of 80% or higher.
+ *
+ * @module comprehension-quiz
+ *
+ * @example
+ * ```ts
+ * import { QuizExecutor } from './comprehension-quiz/quiz-executor.js';
+ * import { QuizQuestionStream, getQuestionCount } from './comprehension-quiz/question-generator.js';
+ *
+ * // Create on-demand stream — NO questions generated yet
+ * const totalQuestions = getQuestionCount(totalArtifactBytes);
+ * const stream = await QuizQuestionStream.create(artifactPaths, totalQuestions);
+ *
+ * // Execute quiz — one question fetched per answer
+ * const executor = new QuizExecutor();
+ * const result = await executor.executeQuiz(stream, changeName);
+ *
+ * if (result.passed) {
+ *   console.log('Quiz passed! Proceeding with implementation.');
+ * } else {
+ *   console.log('Quiz failed. Please review the artifacts and try again.');
+ * }
+ * ```
+ */
+// Types
+export * from './types.js';
+// Providers
+export * from './providers/interface.js';
+export * from './providers/factory.js';
+export { OpenAIProvider } from './providers/openai.js';
+export { AnthropicProvider } from './providers/anthropic.js';
+export { OllamaProvider } from './providers/ollama.js';
+export { LocalProvider } from './providers/local.js';
+// Core utilities
+export { fingerprintFile, fingerprintDirectory, fingerprintArtifacts, isPassRecordValid } from './fingerprint.js';
+export * from './pass-record.js';
+// Quiz execution
+export { QuizExecutor } from './quiz-executor.js';
+// Question generation
+export { generateQuizQuestions, generateQuestionsForArtifact, getQuestionCount, calculateQuestionAllocation, QuizQuestionStream, } from './question-generator.js';
+//# sourceMappingURL=index.js.map

package/dist/comprehension-quiz/pass-record.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Pass record storage and validation
+ *
+ * This module handles the storage and retrieval of quiz pass records. Pass records
+ * are stored in `.openspec/comprehension-quiz-passes.json` and include fingerprint
+ * information to detect when artifacts have changed since the quiz was passed.
+ *
+ * @module comprehension-quiz/pass-record
+ */
+import type { PassRecord } from './types.js';
+/**
+ * Get pass record for a specific change
+ *
+ * @param changeName - Name of the change
+ * @returns Pass record or undefined if not found
+ */
+export declare function getPassRecord(changeName: string): Promise<PassRecord | undefined>;
+/**
+ * Save pass record for a change
+ *
+ * @param record - Pass record to save
+ */
+export declare function savePassRecord(record: PassRecord): Promise<void>;
+/**
+ * Increment failure count for a change
+ *
+ * @param changeName - Name of the change
+ */
+export declare function incrementFailureCount(changeName: string): Promise<void>;
+/**
+ * Delete pass record for a change
+ *
+ * @param changeName - Name of the change
+ */
+export declare function deletePassRecord(changeName: string): Promise<void>;
+/**
+ * Check if a pass record is valid for current artifact fingerprint
+ *
+ * @param changeName - Name of the change
+ * @param currentFingerprint - Current fingerprint of artifacts
+ * @returns True if pass record exists and fingerprint matches
+ */
+export declare function isPassRecordValid(changeName: string, currentFingerprint: string): Promise<boolean>;
+//# sourceMappingURL=pass-record.d.ts.map

package/dist/comprehension-quiz/pass-record.js

@@ -0,0 +1,98 @@
+/**
+ * Pass record storage and validation
+ *
+ * This module handles the storage and retrieval of quiz pass records. Pass records
+ * are stored in `.openspec/comprehension-quiz-passes.json` and include fingerprint
+ * information to detect when artifacts have changed since the quiz was passed.
+ *
+ * @module comprehension-quiz/pass-record
+ */
+import { promises as fs } from 'fs';
+import path from 'path';
+/**
+ * Path to the pass records file
+ */
+const PASS_RECORDS_FILE = '.openspec/comprehension-quiz-passes.json';
+/**
+ * Read all pass records from storage
+ *
+ * @returns Pass records object
+ */
+async function readPassRecords() {
+    try {
+        const content = await fs.readFile(PASS_RECORDS_FILE, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch (error) {
+        // File doesn't exist or is invalid, return empty object
+        return {};
+    }
+}
+/**
+ * Write pass records to storage
+ *
+ * @param records - Pass records to write
+ */
+async function writePassRecords(records) {
+    const dir = path.dirname(PASS_RECORDS_FILE);
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(PASS_RECORDS_FILE, JSON.stringify(records, null, 2), 'utf-8');
+}
+/**
+ * Get pass record for a specific change
+ *
+ * @param changeName - Name of the change
+ * @returns Pass record or undefined if not found
+ */
+export async function getPassRecord(changeName) {
+    const records = await readPassRecords();
+    return records[changeName];
+}
+/**
+ * Save pass record for a change
+ *
+ * @param record - Pass record to save
+ */
+export async function savePassRecord(record) {
+    const records = await readPassRecords();
+    records[record.changeName] = record;
+    await writePassRecords(records);
+}
+/**
+ * Increment failure count for a change
+ *
+ * @param changeName - Name of the change
+ */
+export async function incrementFailureCount(changeName) {
+    const records = await readPassRecords();
+    const record = records[changeName];
+    if (record) {
+        record.failureCount = (record.failureCount || 0) + 1;
+        await writePassRecords(records);
+    }
+}
+/**
+ * Delete pass record for a change
+ *
+ * @param changeName - Name of the change
+ */
+export async function deletePassRecord(changeName) {
+    const records = await readPassRecords();
+    delete records[changeName];
+    await writePassRecords(records);
+}
+/**
+ * Check if a pass record is valid for current artifact fingerprint
+ *
+ * @param changeName - Name of the change
+ * @param currentFingerprint - Current fingerprint of artifacts
+ * @returns True if pass record exists and fingerprint matches
+ */
+export async function isPassRecordValid(changeName, currentFingerprint) {
+    const record = await getPassRecord(changeName);
+    if (!record) {
+        return false;
+    }
+    return record.fingerprint === currentFingerprint;
+}
+//# sourceMappingURL=pass-record.js.map

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

@@ -0,0 +1,35 @@
+/**
+ * Anthropic provider implementation
+ *
+ * This module implements the Anthropic LLM provider for question generation.
+ * It uses the Anthropic API to generate quiz questions from artifact content.
+ *
+ * @module comprehension-quiz/providers/anthropic
+ */
+import { BaseProvider } from './interface.js';
+import type { ProviderConfig, Question } from '../types.js';
+/**
+ * Anthropic provider for question generation
+ *
+ * Requires ANTHROPIC_API_KEY environment variable to be set.
+ */
+export declare class AnthropicProvider extends BaseProvider {
+    constructor(config: ProviderConfig);
+    /**
+     * Validate Anthropic configuration
+     *
+     * @throws Error if API key is missing
+     */
+    validateConfig(): void;
+    /**
+     * Generate quiz questions using Anthropic 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[]>;
+    generateSingleQuestion(artifactContent: string, artifactType: 'proposal' | 'design' | 'specs' | 'plan' | 'tasks', questionIndex: number, totalQuestions: number, previousQuestionTexts: string[]): Promise<Question>;
+}
+//# sourceMappingURL=anthropic.d.ts.map

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

@@ -0,0 +1,69 @@
+/**
+ * Anthropic provider implementation
+ *
+ * This module implements the Anthropic LLM provider for question generation.
+ * It uses the Anthropic API to generate quiz questions from artifact content.
+ *
+ * @module comprehension-quiz/providers/anthropic
+ */
+import { BaseProvider } from './interface.js';
+/**
+ * Anthropic provider for question generation
+ *
+ * Requires ANTHROPIC_API_KEY environment variable to be set.
+ */
+export class AnthropicProvider extends BaseProvider {
+    constructor(config) {
+        super(config);
+    }
+    /**
+     * Validate Anthropic configuration
+     *
+     * @throws Error if API key is missing
+     */
+    validateConfig() {
+        if (!this.config.apiKey) {
+            throw new Error('ANTHROPIC_API_KEY environment variable is required for Anthropic provider');
+        }
+    }
+    /**
+     * Generate quiz questions using Anthropic 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) {
+        const questions = [];
+        for (let i = 0; i < questionCount; i++) {
+            const q = await this.generateSingleQuestion(artifactContent, artifactType, i, questionCount, questions.map((q) => q.text));
+            questions.push(q);
+        }
+        return questions;
+    }
+    async generateSingleQuestion(artifactContent, artifactType, questionIndex, totalQuestions, previousQuestionTexts) {
+        const { system, user } = this.buildSingleQuestionPrompt(artifactContent, artifactType, questionIndex, totalQuestions, previousQuestionTexts);
+        const response = await fetch('https://api.anthropic.com/v1/messages', {
+            method: 'POST',
+            headers: {
+                'x-api-key': this.config.apiKey,
+                'anthropic-version': '2023-06-01',
+                'content-type': 'application/json',
+            },
+            body: JSON.stringify({
+                model: this.config.model ?? 'claude-3-opus-20240229',
+                max_tokens: 512,
+                system,
+                messages: [{ role: 'user', content: user }],
+            }),
+        });
+        if (!response.ok) {
+            throw new Error(`Anthropic API error ${response.status}: ${await response.text()}`);
+        }
+        const data = (await response.json());
+        const raw = data.content.find((b) => b.type === 'text')?.text ?? '';
+        return this.parseSingleQuestionResponse(raw, artifactType);
+    }
+}
+//# sourceMappingURL=anthropic.js.map

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

@@ -0,0 +1,44 @@
+/**
+ * Provider factory for creating LLM provider instances
+ *
+ * This module handles provider selection via environment variables, configuration
+ * loading, and fallback chain management. It supports OpenAI, Anthropic, Ollama, and
+ * local model providers with automatic fallback on failure.
+ *
+ * @module comprehension-quiz/providers/factory
+ */
+import type { LLMProvider } from '../types.js';
+/**
+ * Supported provider types
+ */
+export type ProviderType = 'openai' | 'anthropic' | 'ollama' | 'local';
+/**
+ * Create a provider instance
+ *
+ * @param providerType - Type of provider to create
+ * @returns Provider instance
+ * @throws Error if provider cannot be loaded
+ */
+export declare function createProvider(providerType: ProviderType): Promise<LLMProvider>;
+/**
+ * Create a provider with fallback chain
+ *
+ * Tries each provider in the fallback chain until one succeeds.
+ *
+ * @returns Provider instance from first available provider in fallback chain
+ * @throws Error if all providers fail
+ */
+export declare function createProviderWithFallback(): Promise<LLMProvider>;
+/**
+ * Get the primary provider type
+ *
+ * @returns Provider type
+ */
+export declare function getPrimaryProviderType(): ProviderType;
+/**
+ * Get the fallback chain
+ *
+ * @returns Array of provider types in fallback order
+ */
+export declare function getFallbackChainTypes(): ProviderType[];
+//# sourceMappingURL=factory.d.ts.map

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

@@ -0,0 +1,174 @@
+/**
+ * Provider factory for creating LLM provider instances
+ *
+ * This module handles provider selection via environment variables, configuration
+ * loading, and fallback chain management. It supports OpenAI, Anthropic, Ollama, and
+ * local model providers with automatic fallback on failure.
+ *
+ * @module comprehension-quiz/providers/factory
+ */
+/**
+ * Default fallback chain for providers
+ *
+ * The system will try providers in this order until one succeeds.
+ */
+const DEFAULT_FALLBACK_CHAIN = ['openai', 'anthropic', 'ollama', 'local'];
+/**
+ * Environment variable names for provider selection
+ */
+const ENV_PROVIDER = 'OPENSPEC_LLM_PROVIDER';
+const ENV_FALLBACK = 'OPENSPEC_LLM_FALLBACK';
+/**
+ * Provider-specific environment variables
+ *
+ * Maps each provider to its configuration environment variables.
+ */
+const PROVIDER_ENV_VARS = {
+    openai: {
+        apiKey: 'OPENAI_API_KEY',
+        model: 'OPENAI_MODEL',
+    },
+    anthropic: {
+        apiKey: 'ANTHROPIC_API_KEY',
+        model: 'ANTHROPIC_MODEL',
+    },
+    ollama: {
+        endpoint: 'OLLAMA_BASE_URL',
+        model: 'OLLAMA_MODEL',
+    },
+    local: {
+        modelType: 'LOCAL_MODEL_TYPE',
+        model: 'LOCAL_MODEL_PATH',
+    },
+};
+/**
+ * Default model names for each provider
+ *
+ * These are used if no specific model is configured via environment variables.
+ */
+const DEFAULT_MODELS = {
+    openai: 'gpt-4',
+    anthropic: 'claude-3-opus',
+    ollama: 'llama2',
+    local: 'local-model',
+};
+/**
+ * Get provider type from environment variable
+ *
+ * @returns Provider type or default
+ */
+function getProviderType() {
+    const envValue = process.env[ENV_PROVIDER];
+    if (envValue && ['openai', 'anthropic', 'ollama', 'local'].includes(envValue)) {
+        return envValue;
+    }
+    return 'openai'; // Default
+}
+/**
+ * Get fallback chain from environment variable
+ *
+ * @returns Array of provider types in fallback order
+ */
+function getFallbackChain() {
+    const envValue = process.env[ENV_FALLBACK];
+    if (envValue) {
+        const providers = envValue.split(',').map((p) => p.trim().toLowerCase());
+        const validProviders = providers.filter((p) => ['openai', 'anthropic', 'ollama', 'local'].includes(p));
+        if (validProviders.length > 0) {
+            return validProviders;
+        }
+    }
+    return DEFAULT_FALLBACK_CHAIN;
+}
+/**
+ * Get configuration for a provider type from environment variables
+ *
+ * @param providerType - Type of provider
+ * @returns Provider configuration
+ */
+function getProviderConfig(providerType) {
+    const envVars = PROVIDER_ENV_VARS[providerType];
+    const config = {};
+    if (envVars.apiKey && process.env[envVars.apiKey]) {
+        config.apiKey = process.env[envVars.apiKey];
+    }
+    if (envVars.model && process.env[envVars.model]) {
+        config.model = process.env[envVars.model];
+    }
+    else {
+        config.model = DEFAULT_MODELS[providerType];
+    }
+    if (envVars.endpoint && process.env[envVars.endpoint]) {
+        config.endpoint = process.env[envVars.endpoint];
+    }
+    if (envVars.modelType && process.env[envVars.modelType]) {
+        config.modelType = process.env[envVars.modelType];
+    }
+    return config;
+}
+/**
+ * Create a provider instance
+ *
+ * @param providerType - Type of provider to create
+ * @returns Provider instance
+ * @throws Error if provider cannot be loaded
+ */
+export async function createProvider(providerType) {
+    const config = getProviderConfig(providerType);
+    switch (providerType) {
+        case 'openai':
+            const { OpenAIProvider } = await import('./openai.js');
+            return new OpenAIProvider(config);
+        case 'anthropic':
+            const { AnthropicProvider } = await import('./anthropic.js');
+            return new AnthropicProvider(config);
+        case 'ollama':
+            const { OllamaProvider } = await import('./ollama.js');
+            return new OllamaProvider(config);
+        case 'local':
+            const { LocalProvider } = await import('./local.js');
+            return new LocalProvider(config);
+        default:
+            throw new Error(`Unknown provider type: ${providerType}`);
+    }
+}
+/**
+ * Create a provider with fallback chain
+ *
+ * Tries each provider in the fallback chain until one succeeds.
+ *
+ * @returns Provider instance from first available provider in fallback chain
+ * @throws Error if all providers fail
+ */
+export async function createProviderWithFallback() {
+    const fallbackChain = getFallbackChain();
+    const errors = [];
+    for (const providerType of fallbackChain) {
+        try {
+            const provider = await createProvider(providerType);
+            return provider;
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            errors.push(`${providerType}: ${errorMessage}`);
+        }
+    }
+    throw new Error(`All LLM providers failed. Attempted: ${fallbackChain.join(', ')}. Errors: ${errors.join('; ')}`);
+}
+/**
+ * Get the primary provider type
+ *
+ * @returns Provider type
+ */
+export function getPrimaryProviderType() {
+    return getProviderType();
+}
+/**
+ * Get the fallback chain
+ *
+ * @returns Array of provider types in fallback order
+ */
+export function getFallbackChainTypes() {
+    return getFallbackChain();
+}
+//# sourceMappingURL=factory.js.map

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

@@ -0,0 +1,98 @@
+/**
+ * LLM provider interface for question generation
+ *
+ * This module defines the abstract base class that all LLM providers must implement.
+ * The interface ensures consistent question generation across different backends (OpenAI,
+ * Anthropic, Ollama, local models) with validation of generated questions.
+ *
+ * @module comprehension-quiz/providers/interface
+ */
+import type { LLMProvider, ProviderConfig, Question } from '../types.js';
+/**
+ * Abstract base class for LLM providers
+ *
+ * All providers must extend this class and implement the abstract methods.
+ * Provides common validation logic for generated questions.
+ *
+ * @example
+ * ```ts
+ * class MyProvider extends BaseProvider {
+ *   async generateQuestions(content, count, type) {
+ *     // Generate questions using your LLM
+ *   }
+ *   validateConfig() {
+ *     // Check your configuration
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class BaseProvider implements LLMProvider {
+    protected config: ProviderConfig;
+    constructor(config: ProviderConfig);
+    /**
+     * Generate quiz questions from artifact content
+     * @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
+     */
+    abstract generateQuestions(artifactContent: string, questionCount: number, artifactType: 'proposal' | 'design' | 'specs' | 'plan' | 'tasks'): Promise<Question[]>;
+    /**
+     * Generate a single question on-demand.
+     * Subclasses MUST call buildSingleQuestionPrompt() to get the messages and
+     * parseSingleQuestionResponse() to parse the LLM reply. This guarantees the
+     * correct-answer index never leaks into stdout or conversational context.
+     */
+    abstract generateSingleQuestion(artifactContent: string, artifactType: 'proposal' | 'design' | 'specs' | 'plan' | 'tasks', questionIndex: number, totalQuestions: number, previousQuestionTexts: string[]): Promise<Question>;
+    /**
+     * Validate provider configuration
+     * @throws Error if configuration is invalid
+     */
+    abstract validateConfig(): void;
+    /**
+     * Build the system + user messages for single-question generation.
+     *
+     * Contract:
+     *   - System message explicitly forbids listing multiple questions.
+     *   - User message asks for exactly one question (question N of total).
+     *   - Response format is strict JSON only — no prose, no explanation, no answer label.
+     *   - The correct answer index (correctOption) is returned as a number 0-2; its
+     *     meaning is never explained in the response so the LLM cannot read it back.
+     *
+     * @returns { system, user } message pair ready to send to the LLM API
+     */
+    protected buildSingleQuestionPrompt(artifactContent: string, artifactType: 'proposal' | 'design' | 'specs' | 'plan' | 'tasks', questionIndex: number, totalQuestions: number, previousQuestionTexts: string[]): {
+        system: string;
+        user: string;
+    };
+    /**
+     * Parse the raw LLM text response into a Question object.
+     * Strips markdown fences if present, then JSON-parses and validates.
+     *
+     * @param rawResponse - Raw text returned by the LLM API
+     * @param artifactType - Expected artifact source (used as fallback)
+     * @returns Validated Question object
+     * @throws Error if the response cannot be parsed or fails validation
+     */
+    protected parseSingleQuestionResponse(rawResponse: string, artifactType: 'proposal' | 'design' | 'specs' | 'plan' | 'tasks'): Question;
+    /**
+     * Validate generated questions before returning
+     *
+     * Ensures all questions have:
+     * - Non-empty text
+     * - Exactly 3 options
+     * - Valid correct option index (0-2)
+     * - Valid artifact source
+     *
+     * @param questions - Questions to validate
+     * @throws Error if any question is invalid
+     */
+    protected validateQuestions(questions: Question[]): void;
+    /**
+     * Validate a single question object.
+     * @param question - Question to validate
+     * @throws Error if invalid
+     */
+    protected validateQuestion(question: Question): void;
+}
+//# sourceMappingURL=interface.d.ts.map