specweave 0.6.8 → 0.7.0

package/dist/utils/secrets-loader.js

@@ -0,0 +1,271 @@
+/**
+ * Secrets Loader Utility
+ *
+ * Loads secrets from .specweave/secrets.env file
+ * Provides clear validation and helpful error messages
+ *
+ * DESIGN PHILOSOPHY:
+ * - Secrets are OPTIONAL (framework works without them)
+ * - Clear error messages tell users WHERE to put secrets
+ * - Template file provides step-by-step instructions
+ * - Security by default (gitignored)
+ *
+ * @see .specweave/secrets.env.template
+ */
+import fs from 'fs-extra';
+import path from 'path';
+/**
+ * Secrets registry
+ */
+const SECRETS_CONFIG = {
+    ANTHROPIC_API_KEY: {
+        description: 'Anthropic API key for automatic translation',
+        required: false,
+        validation: (value) => value.startsWith('sk-ant-api03-'),
+        setupInstructions: `
+🔑 ANTHROPIC_API_KEY Setup Instructions:
+
+WHY NEEDED:
+  Enables automatic translation during increment creation.
+  Without this key, translation requires manual intervention.
+
+HOW TO GET IT:
+  1. Visit: https://console.anthropic.com/
+  2. Sign in or create account
+  3. Navigate to "API Keys"
+  4. Click "Create Key"
+  5. Copy your key (starts with "sk-ant-api03-...")
+
+WHERE TO PUT IT:
+  Option A (Recommended): Create .specweave/secrets.env file
+    1. Copy template: cp .specweave/secrets.env.template .specweave/secrets.env
+    2. Edit .specweave/secrets.env
+    3. Add line: ANTHROPIC_API_KEY=sk-ant-api03-YOUR-KEY
+
+  Option B: Set environment variable
+    # macOS/Linux
+    export ANTHROPIC_API_KEY="sk-ant-api03-YOUR-KEY"
+    # Add to ~/.zshrc for permanence
+
+    # Windows PowerShell
+    [System.Environment]::SetEnvironmentVariable('ANTHROPIC_API_KEY', 'sk-ant-api03-YOUR-KEY', 'User')
+
+COST:
+  ~$0.0075 per increment (negligible)
+  ~$0.15 per month (20 increments)
+
+SECURITY:
+  ✓ .specweave/secrets.env is automatically gitignored
+  ✓ Keep your API key private
+  ✓ Rotate periodically
+`,
+    },
+    OPENAI_API_KEY: {
+        description: 'OpenAI API key (alternative to Anthropic)',
+        required: false,
+        validation: (value) => value.startsWith('sk-'),
+        setupInstructions: 'Visit: https://platform.openai.com/api-keys',
+    },
+    GITHUB_TOKEN: {
+        description: 'GitHub Personal Access Token',
+        required: false,
+        validation: (value) => value.length > 20,
+        setupInstructions: 'Visit: https://github.com/settings/tokens',
+    },
+    JIRA_API_TOKEN: {
+        description: 'Jira API Token',
+        required: false,
+        setupInstructions: 'Visit Jira: Account Settings → Security → API Tokens',
+    },
+    JIRA_DOMAIN: {
+        description: 'Jira Domain (e.g., company.atlassian.net)',
+        required: false,
+        setupInstructions: 'Your Jira domain from the URL',
+    },
+    JIRA_EMAIL: {
+        description: 'Jira Account Email',
+        required: false,
+        setupInstructions: 'Email associated with your Jira account',
+    },
+    AZURE_DEVOPS_PAT: {
+        description: 'Azure DevOps Personal Access Token',
+        required: false,
+        setupInstructions: 'Visit: Azure DevOps → User Settings → Personal Access Tokens',
+    },
+    AZURE_DEVOPS_ORG: {
+        description: 'Azure DevOps Organization',
+        required: false,
+        setupInstructions: 'Your Azure DevOps organization name',
+    },
+};
+/**
+ * Find project root by searching for .specweave/ directory
+ */
+function findProjectRoot(startDir = process.cwd()) {
+    let currentDir = startDir;
+    const root = path.parse(currentDir).root;
+    while (currentDir !== root) {
+        const specweavePath = path.join(currentDir, '.specweave');
+        if (fs.existsSync(specweavePath)) {
+            return currentDir;
+        }
+        currentDir = path.dirname(currentDir);
+    }
+    return null;
+}
+/**
+ * Load secrets from .specweave/secrets.env file
+ *
+ * @param projectRoot - Project root directory (auto-detected if not provided)
+ * @returns Map of loaded secrets
+ */
+export function loadSecrets(projectRoot) {
+    const secrets = new Map();
+    // Find project root
+    const root = projectRoot || findProjectRoot();
+    if (!root) {
+        return secrets; // No project root found, return empty
+    }
+    const secretsPath = path.join(root, '.specweave', 'secrets.env');
+    // Check if secrets.env exists
+    if (!fs.existsSync(secretsPath)) {
+        // No secrets file, return empty (this is OK - secrets are optional)
+        return secrets;
+    }
+    // Read and parse secrets.env
+    try {
+        const content = fs.readFileSync(secretsPath, 'utf-8');
+        const lines = content.split('\n');
+        for (const line of lines) {
+            // Skip comments and empty lines
+            if (line.trim().startsWith('#') || !line.trim()) {
+                continue;
+            }
+            // Parse KEY=VALUE
+            const match = line.match(/^([A-Z_]+)=(.*)$/);
+            if (match) {
+                const [, key, value] = match;
+                if (key in SECRETS_CONFIG && value.trim()) {
+                    secrets.set(key, value.trim());
+                }
+            }
+        }
+    }
+    catch (error) {
+        console.error(`⚠️  Failed to load secrets from ${secretsPath}`);
+        console.error(`   Error: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return secrets;
+}
+/**
+ * Get a specific secret
+ *
+ * Priority order:
+ * 1. Environment variable (process.env)
+ * 2. .specweave/secrets.env file
+ * 3. null (not found)
+ *
+ * @param key - Secret key
+ * @param projectRoot - Project root (auto-detected if not provided)
+ * @returns Secret value or null
+ */
+export function getSecret(key, projectRoot) {
+    // Priority 1: Environment variable
+    if (process.env[key]) {
+        return process.env[key];
+    }
+    // Priority 2: secrets.env file
+    const secrets = loadSecrets(projectRoot);
+    return secrets.get(key) || null;
+}
+/**
+ * Validate a secret value
+ *
+ * @param key - Secret key
+ * @param value - Secret value
+ * @returns true if valid, false otherwise
+ */
+export function validateSecret(key, value) {
+    const config = SECRETS_CONFIG[key];
+    if (!config.validation) {
+        return true; // No validation function, assume valid
+    }
+    return config.validation(value);
+}
+/**
+ * Get setup instructions for a secret
+ *
+ * @param key - Secret key
+ * @returns Setup instructions
+ */
+export function getSetupInstructions(key) {
+    return SECRETS_CONFIG[key].setupInstructions;
+}
+/**
+ * Display helpful error message when a secret is missing
+ *
+ * @param key - Secret key
+ * @param context - Context message (what failed)
+ */
+export function displaySecretMissingError(key, context) {
+    const config = SECRETS_CONFIG[key];
+    console.error('\n' + '='.repeat(80));
+    console.error(`❌ Missing Secret: ${key}`);
+    console.error('='.repeat(80));
+    if (context) {
+        console.error(`\n📋 Context: ${context}\n`);
+    }
+    console.error(`📝 Description: ${config.description}\n`);
+    console.error(`⚙️  Required: ${config.required ? 'Yes' : 'No (optional)'}\n`);
+    console.error(config.setupInstructions);
+    console.error('\n' + '='.repeat(80));
+    console.error('💡 After setting up, retry the operation');
+    console.error('='.repeat(80) + '\n');
+}
+/**
+ * Check if template file exists, create if missing
+ *
+ * @param projectRoot - Project root
+ */
+export function ensureSecretsTemplate(projectRoot) {
+    const root = projectRoot || findProjectRoot();
+    if (!root) {
+        return; // No project root, skip
+    }
+    const templatePath = path.join(root, '.specweave', 'secrets.env.template');
+    if (fs.existsSync(templatePath)) {
+        return; // Template exists, nothing to do
+    }
+    // Template should be created during `specweave init`
+    // If missing, user might be in an old project
+    console.warn('⚠️  Secrets template missing. Run: specweave init --refresh');
+}
+/**
+ * Validate all secrets in secrets.env file
+ *
+ * @param projectRoot - Project root
+ * @returns Validation results
+ */
+export function validateAllSecrets(projectRoot) {
+    const secrets = loadSecrets(projectRoot);
+    const valid = [];
+    const invalid = [];
+    const missing = [];
+    for (const [key, config] of Object.entries(SECRETS_CONFIG)) {
+        const value = getSecret(key, projectRoot);
+        if (!value) {
+            if (config.required) {
+                missing.push(key);
+            }
+            continue;
+        }
+        if (validateSecret(key, value)) {
+            valid.push(key);
+        }
+        else {
+            invalid.push(key);
+        }
+    }
+    return { valid, invalid, missing };
+}
+//# sourceMappingURL=secrets-loader.js.map

package/dist/utils/secrets-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets-loader.js","sourceRoot":"","sources":["../../src/utils/secrets-loader.ts"],"names":[],"mappings":"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"}

package/dist/utils/translation.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Translation Utilities
+ *
+ * LLM-native translation system for SpecWeave multilingual support.
+ * Provides zero-cost language detection and cost-efficient translation
+ * using Claude Haiku via current LLM session.
+ *
+ * Strategy:
+ * - Language Detection: Simple heuristic (no API calls, <1ms)
+ * - Translation: Claude Haiku via current session (~$0.0025 per file)
+ * - Preservation: Markdown, code blocks, technical terms stay intact
+ *
+ * @see .specweave/increments/0006-llm-native-i18n/reports/DESIGN-POST-GENERATION-TRANSLATION.md
+ */
+/**
+ * Supported languages for translation
+ */
+export type SupportedLanguage = 'en' | 'ru' | 'es' | 'zh' | 'de' | 'fr' | 'ja' | 'ko' | 'pt' | 'ar' | 'he' | 'unknown';
+/**
+ * Language detection result
+ */
+export interface LanguageDetectionResult {
+    language: SupportedLanguage;
+    confidence: number;
+    nonAsciiRatio: number;
+    detectionMethod: 'heuristic' | 'explicit';
+}
+/**
+ * Preserved content structure for code blocks
+ */
+export interface PreservedContent {
+    preserved: string;
+    blocks: string[];
+    inlineCode: string[];
+    links: string[];
+}
+/**
+ * Translation result with metadata
+ */
+export interface TranslationResult {
+    translated: string;
+    sourceLanguage: SupportedLanguage;
+    targetLanguage: SupportedLanguage;
+    estimatedTokens: number;
+    estimatedCost: number;
+    preservedBlocks: number;
+}
+/**
+ * Detects the language of the given content using simple heuristics
+ *
+ * @param content - The text content to analyze
+ * @returns Language detection result with confidence score
+ *
+ * @example
+ * ```typescript
+ * const result = detectLanguage('Это тестовый документ');
+ * console.log(result.language); // 'ru'
+ * console.log(result.confidence); // 0.95
+ * ```
+ */
+export declare function detectLanguage(content: string): LanguageDetectionResult;
+/**
+ * Detects specific language from content
+ *
+ * @param content - The text content to analyze
+ * @returns Detected language code or 'unknown'
+ *
+ * @example
+ * ```typescript
+ * detectSpecificLanguage('Это текст'); // 'ru'
+ * detectSpecificLanguage('这是文本'); // 'zh'
+ * ```
+ */
+export declare function detectSpecificLanguage(content: string): SupportedLanguage;
+/**
+ * Preserves code blocks, inline code, and links before translation
+ *
+ * @param content - Markdown content to preserve
+ * @returns Preserved content with placeholders
+ *
+ * @example
+ * ```typescript
+ * const content = 'Text\n```js\ncode\n```\nMore text';
+ * const preserved = preserveCodeBlocks(content);
+ * // preserved.blocks = ['```js\ncode\n```']
+ * // preserved.preserved = 'Text\n__CODE_BLOCK_0__\nMore text'
+ * ```
+ */
+export declare function preserveCodeBlocks(content: string): PreservedContent;
+/**
+ * Restores preserved code blocks, inline code, and links after translation
+ *
+ * @param translated - Translated text with placeholders
+ * @param preserved - Preserved content structure
+ * @returns Restored text with original code blocks and links
+ *
+ * @example
+ * ```typescript
+ * const translated = 'Текст\n__CODE_BLOCK_0__\nБольше текста';
+ * const preserved = { blocks: ['```js\ncode\n```'], inlineCode: [], links: [] };
+ * const restored = restoreCodeBlocks(translated, preserved);
+ * // Result: 'Текст\n```js\ncode\n```\nБольше текста'
+ * ```
+ */
+export declare function restoreCodeBlocks(translated: string, preserved: Pick<PreservedContent, 'blocks' | 'inlineCode' | 'links'>): string;
+/**
+ * Estimates the number of tokens in a text
+ * Rule of thumb: ~4 characters per token for English, ~2-3 for other languages
+ *
+ * @param text - Text to estimate
+ * @param language - Language code for estimation
+ * @returns Estimated token count
+ */
+export declare function estimateTokens(text: string, language?: SupportedLanguage): number;
+/**
+ * Estimates translation cost using Claude Haiku pricing
+ * Haiku pricing (as of 2025): $0.25 per 1M input tokens, $1.25 per 1M output tokens
+ *
+ * @param inputTokens - Input token count
+ * @param outputTokens - Output token count (defaults to input for balanced estimate)
+ * @returns Estimated cost in USD
+ */
+export declare function estimateTranslationCost(inputTokens: number, outputTokens?: number): number;
+/**
+ * Generates translation prompt for LLM
+ *
+ * @param content - Content to translate
+ * @param sourceLanguage - Source language code
+ * @param targetLanguage - Target language code (default: 'en')
+ * @returns Translation prompt for LLM
+ */
+export declare function generateTranslationPrompt(content: string, sourceLanguage: SupportedLanguage, targetLanguage?: SupportedLanguage): string;
+/**
+ * Translates content to English using LLM (Claude Haiku)
+ * This function generates the prompt but delegates actual LLM invocation
+ * to the caller (via Task tool, skill, or direct API)
+ *
+ * @param content - Content to translate
+ * @param sourceLanguage - Source language code
+ * @returns Translation prompt and metadata (caller must invoke LLM)
+ *
+ * @example
+ * ```typescript
+ * const content = 'Это тестовый документ';
+ * const result = prepareTranslation(content, 'ru');
+ * // Caller then invokes LLM with result.prompt
+ * ```
+ */
+export declare function prepareTranslation(content: string, sourceLanguage: SupportedLanguage, targetLanguage?: SupportedLanguage): {
+    prompt: string;
+    preserved: PreservedContent;
+    estimatedTokens: number;
+    estimatedCost: number;
+};
+/**
+ * Post-processes translated content
+ * Restores code blocks, validates markdown, cleans up extra whitespace
+ *
+ * @param translated - Translated text from LLM
+ * @param preserved - Preserved content structure
+ * @returns Cleaned and restored translated content
+ */
+export declare function postProcessTranslation(translated: string, preserved: PreservedContent): string;
+/**
+ * Validates that translated content preserves markdown structure
+ * Returns warnings if structure doesn't match
+ *
+ * @param original - Original content
+ * @param translated - Translated content
+ * @returns Array of validation warnings (empty if valid)
+ */
+export declare function validateTranslation(original: string, translated: string): string[];
+/**
+ * Gets human-readable language name
+ *
+ * @param code - Language code
+ * @returns Human-readable name
+ */
+export declare function getLanguageName(code: SupportedLanguage): string;
+/**
+ * Formats cost for display
+ *
+ * @param cost - Cost in USD
+ * @returns Formatted string (e.g., "$0.0025" or "<$0.001")
+ */
+export declare function formatCost(cost: number): string;
+//# sourceMappingURL=translation.d.ts.map

package/dist/utils/translation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"translation.d.ts","sourceRoot":"","sources":["../../src/utils/translation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;GAEG;AACH,MAAM,MAAM,iBAAiB,GACzB,IAAI,GACJ,IAAI,GACJ,IAAI,GACJ,IAAI,GACJ,IAAI,GACJ,IAAI,GACJ,IAAI,GACJ,IAAI,GACJ,IAAI,GACJ,IAAI,GACJ,IAAI,GACJ,SAAS,CAAC;AAEd;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,WAAW,GAAG,UAAU,CAAC;CAC3C;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,iBAAiB,CAAC;IAClC,cAAc,EAAE,iBAAiB,CAAC;IAClC,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;CACzB;AA4CD;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,uBAAuB,CAmCvE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,iBAAiB,CAgCzE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,CA6BpE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,IAAI,CAAC,gBAAgB,EAAE,QAAQ,GAAG,YAAY,GAAG,OAAO,CAAC,GACnE,MAAM,CAqBR;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,GAAE,iBAAwB,GAAG,MAAM,CAGvF;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,MAAM,EACnB,YAAY,CAAC,EAAE,MAAM,GACpB,MAAM,CAUR;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,iBAAiB,EACjC,cAAc,GAAE,iBAAwB,GACvC,MAAM,CAiDR;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,iBAAiB,EACjC,cAAc,GAAE,iBAAwB,GACvC;IACD,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,gBAAgB,CAAC;IAC5B,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;CACvB,CAkBA;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,gBAAgB,GAC1B,MAAM,CAaR;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,MAAM,EAAE,CA0CV;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,CAiB/D;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAK/C"}