specweave 0.1.9 → 0.3.1

package/dist/core/credentials-manager.js

@@ -0,0 +1,271 @@
+/**
+ * Secure Credentials Manager
+ *
+ * Handles API keys and credentials for external integrations (Jira, ADO, etc.)
+ * - Loads from .env file or environment variables
+ * - Validates credential format
+ * - Never logs secrets
+ * - Provides masked logging for debugging
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+export class CredentialsManager {
+    constructor() {
+        this.credentials = {};
+        this.envLoaded = false;
+        this.loadFromEnv();
+    }
+    static getInstance() {
+        if (!CredentialsManager.instance) {
+            CredentialsManager.instance = new CredentialsManager();
+        }
+        return CredentialsManager.instance;
+    }
+    /**
+     * Load credentials from .env file or environment variables
+     */
+    loadFromEnv() {
+        // First, try to load from .env file
+        const envPath = path.join(process.cwd(), '.env');
+        if (fs.existsSync(envPath)) {
+            const envContent = fs.readFileSync(envPath, 'utf-8');
+            const envVars = this.parseEnvFile(envContent);
+            // Merge with process.env (process.env takes precedence)
+            Object.keys(envVars).forEach(key => {
+                if (!process.env[key]) {
+                    process.env[key] = envVars[key];
+                }
+            });
+        }
+        // Load ADO credentials
+        if (process.env.AZURE_DEVOPS_PAT) {
+            this.credentials.ado = {
+                pat: process.env.AZURE_DEVOPS_PAT,
+                organization: process.env.AZURE_DEVOPS_ORG || '',
+                project: process.env.AZURE_DEVOPS_PROJECT || ''
+            };
+        }
+        // Load Jira credentials
+        if (process.env.JIRA_API_TOKEN) {
+            this.credentials.jira = {
+                apiToken: process.env.JIRA_API_TOKEN,
+                email: process.env.JIRA_EMAIL || '',
+                domain: process.env.JIRA_DOMAIN || ''
+            };
+        }
+        this.envLoaded = true;
+    }
+    /**
+     * Parse .env file content into key-value pairs
+     */
+    parseEnvFile(content) {
+        const result = {};
+        const lines = content.split('\n');
+        for (const line of lines) {
+            const trimmed = line.trim();
+            // Skip empty lines and comments
+            if (!trimmed || trimmed.startsWith('#')) {
+                continue;
+            }
+            // Parse KEY=VALUE
+            const match = trimmed.match(/^([^=]+)=(.*)$/);
+            if (match) {
+                const key = match[1].trim();
+                let value = match[2].trim();
+                // Remove quotes if present
+                if ((value.startsWith('"') && value.endsWith('"')) ||
+                    (value.startsWith("'") && value.endsWith("'"))) {
+                    value = value.slice(1, -1);
+                }
+                result[key] = value;
+            }
+        }
+        return result;
+    }
+    /**
+     * Get ADO credentials
+     * @throws Error if credentials not found
+     */
+    getAdoCredentials() {
+        if (!this.credentials.ado) {
+            throw new Error('Azure DevOps credentials not found. Please set AZURE_DEVOPS_PAT, ' +
+                'AZURE_DEVOPS_ORG, and AZURE_DEVOPS_PROJECT in .env file or environment variables.');
+        }
+        this.validateAdoCredentials(this.credentials.ado);
+        return this.credentials.ado;
+    }
+    /**
+     * Get Jira credentials
+     * @throws Error if credentials not found
+     */
+    getJiraCredentials() {
+        if (!this.credentials.jira) {
+            throw new Error('Jira credentials not found. Please set JIRA_API_TOKEN, JIRA_EMAIL, ' +
+                'and JIRA_DOMAIN in .env file or environment variables.');
+        }
+        this.validateJiraCredentials(this.credentials.jira);
+        return this.credentials.jira;
+    }
+    /**
+     * Check if ADO credentials are available
+     */
+    hasAdoCredentials() {
+        return !!this.credentials.ado?.pat;
+    }
+    /**
+     * Check if Jira credentials are available
+     */
+    hasJiraCredentials() {
+        return !!this.credentials.jira?.apiToken;
+    }
+    /**
+     * Validate ADO credentials format
+     */
+    validateAdoCredentials(creds) {
+        if (!creds.pat || creds.pat.length !== 52) {
+            console.warn(`⚠️  Azure DevOps PAT length unexpected. Expected: 52 characters, Got: ${creds.pat.length}`);
+        }
+        if (!creds.organization || !/^[a-zA-Z0-9-]+$/.test(creds.organization)) {
+            throw new Error(`Invalid Azure DevOps organization: "${creds.organization}". ` +
+                'Expected: alphanumeric and hyphens only.');
+        }
+        if (!creds.project) {
+            throw new Error('Azure DevOps project name is required.');
+        }
+    }
+    /**
+     * Validate Jira credentials format
+     */
+    validateJiraCredentials(creds) {
+        const emailRegex = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;
+        if (!emailRegex.test(creds.email)) {
+            throw new Error(`Invalid Jira email: "${creds.email}". Expected: valid email address.`);
+        }
+        if (!creds.domain.includes('.atlassian.net') && !creds.domain.includes('://')) {
+            console.warn(`⚠️  Jira domain format unexpected: "${creds.domain}". ` +
+                'Expected: *.atlassian.net or custom domain with protocol.');
+        }
+        if (!creds.apiToken) {
+            throw new Error('Jira API token is required.');
+        }
+    }
+    /**
+     * Get masked version of credentials for logging (safe to display)
+     */
+    getMaskedAdoInfo() {
+        if (!this.credentials.ado) {
+            return 'ADO credentials: Not configured';
+        }
+        return [
+            'ADO credentials:',
+            `  PAT: ${this.maskSecret(this.credentials.ado.pat)}`,
+            `  Organization: ${this.credentials.ado.organization}`,
+            `  Project: ${this.credentials.ado.project}`
+        ].join('\n');
+    }
+    /**
+     * Get masked version of credentials for logging (safe to display)
+     */
+    getMaskedJiraInfo() {
+        if (!this.credentials.jira) {
+            return 'Jira credentials: Not configured';
+        }
+        return [
+            'Jira credentials:',
+            `  API Token: ${this.maskSecret(this.credentials.jira.apiToken)}`,
+            `  Email: ${this.credentials.jira.email}`,
+            `  Domain: ${this.credentials.jira.domain}`
+        ].join('\n');
+    }
+    /**
+     * Mask a secret for safe logging
+     */
+    maskSecret(secret) {
+        if (!secret)
+            return '[EMPTY]';
+        if (secret.length <= 8)
+            return '****';
+        const visibleChars = 4;
+        const start = secret.slice(0, visibleChars);
+        const end = secret.slice(-visibleChars);
+        return `${start}...${end} (${secret.length} chars)`;
+    }
+    /**
+     * Save credentials to .env file (with backup)
+     */
+    saveToEnvFile(config) {
+        const envPath = path.join(process.cwd(), '.env');
+        // Backup existing .env
+        if (fs.existsSync(envPath)) {
+            const backup = `${envPath}.backup.${Date.now()}`;
+            fs.copyFileSync(envPath, backup);
+            console.log(`📦 Backed up existing .env to: ${backup}`);
+        }
+        // Read existing content
+        let existingContent = '';
+        let existingVars = {};
+        if (fs.existsSync(envPath)) {
+            existingContent = fs.readFileSync(envPath, 'utf-8');
+            existingVars = this.parseEnvFile(existingContent);
+        }
+        // Update with new credentials
+        if (config.ado) {
+            existingVars.AZURE_DEVOPS_PAT = config.ado.pat;
+            existingVars.AZURE_DEVOPS_ORG = config.ado.organization;
+            existingVars.AZURE_DEVOPS_PROJECT = config.ado.project;
+        }
+        if (config.jira) {
+            existingVars.JIRA_API_TOKEN = config.jira.apiToken;
+            existingVars.JIRA_EMAIL = config.jira.email;
+            existingVars.JIRA_DOMAIN = config.jira.domain;
+        }
+        // Write back to .env
+        const newContent = Object.entries(existingVars)
+            .map(([key, value]) => `${key}=${value}`)
+            .join('\n');
+        fs.writeFileSync(envPath, newContent + '\n', 'utf-8');
+        console.log('✅ Credentials saved to .env');
+        // Ensure .env is in .gitignore
+        this.ensureGitignore();
+        // Reload credentials
+        this.loadFromEnv();
+    }
+    /**
+     * Ensure .env is in .gitignore
+     */
+    ensureGitignore() {
+        const gitignorePath = path.join(process.cwd(), '.gitignore');
+        let gitignoreContent = '';
+        if (fs.existsSync(gitignorePath)) {
+            gitignoreContent = fs.readFileSync(gitignorePath, 'utf-8');
+        }
+        if (!gitignoreContent.includes('.env')) {
+            fs.appendFileSync(gitignorePath, '\n# Environment variables\n.env\n.env.*.backup\n');
+            console.log('✅ Added .env to .gitignore');
+        }
+    }
+    /**
+     * Create .env.example file for team
+     */
+    createEnvExample() {
+        const examplePath = path.join(process.cwd(), '.env.example');
+        const exampleContent = `# Azure DevOps Personal Access Token
+# Get from: https://dev.azure.com/{org}/_usersSettings/tokens
+# Scopes: Work Items (Read, Write, Manage), Code (Read), Project (Read)
+AZURE_DEVOPS_PAT=your-ado-pat-52-chars-base64
+AZURE_DEVOPS_ORG=your-organization-name
+AZURE_DEVOPS_PROJECT=your-project-name
+
+# Jira API Token
+# Get from: https://id.atlassian.com/manage-profile/security/api-tokens
+JIRA_API_TOKEN=your-jira-api-token
+JIRA_EMAIL=your-email@example.com
+JIRA_DOMAIN=your-domain.atlassian.net
+`;
+        fs.writeFileSync(examplePath, exampleContent, 'utf-8');
+        console.log('✅ Created .env.example (safe to commit)');
+    }
+}
+// Export singleton instance
+export const credentialsManager = CredentialsManager.getInstance();
+//# sourceMappingURL=credentials-manager.js.map

package/dist/core/credentials-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials-manager.js","sourceRoot":"","sources":["../../src/core/credentials-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAmB7B,MAAM,OAAO,kBAAkB;IAK7B;QAHQ,gBAAW,GAAsB,EAAE,CAAC;QACpC,cAAS,GAAG,KAAK,CAAC;QAGxB,IAAI,CAAC,WAAW,EAAE,CAAC;IACrB,CAAC;IAEM,MAAM,CAAC,WAAW;QACvB,IAAI,CAAC,kBAAkB,CAAC,QAAQ,EAAE,CAAC;YACjC,kBAAkB,CAAC,QAAQ,GAAG,IAAI,kBAAkB,EAAE,CAAC;QACzD,CAAC;QACD,OAAO,kBAAkB,CAAC,QAAQ,CAAC;IACrC,CAAC;IAED;;OAEG;IACK,WAAW;QACjB,oCAAoC;QACpC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,MAAM,CAAC,CAAC;QACjD,IAAI,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YAC3B,MAAM,UAAU,GAAG,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YACrD,MAAM,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC;YAE9C,wDAAwD;YACxD,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE;gBACjC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;oBACtB,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;gBAClC,CAAC;YACH,CAAC,CAAC,CAAC;QACL,CAAC;QAED,uBAAuB;QACvB,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB,EAAE,CAAC;YACjC,IAAI,CAAC,WAAW,CAAC,GAAG,GAAG;gBACrB,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,gBAAgB;gBACjC,YAAY,EAAE,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,EAAE;gBAChD,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,oBAAoB,IAAI,EAAE;aAChD,CAAC;QACJ,CAAC;QAED,wBAAwB;QACxB,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,CAAC;YAC/B,IAAI,CAAC,WAAW,CAAC,IAAI,GAAG;gBACtB,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,cAAc;gBACpC,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,EAAE;gBACnC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,EAAE;aACtC,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;IACxB,CAAC;IAED;;OAEG;IACK,YAAY,CAAC,OAAe;QAClC,MAAM,MAAM,GAA2B,EAAE,CAAC;QAC1C,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAElC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;YAE5B,gCAAgC;YAChC,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;gBACxC,SAAS;YACX,CAAC;YAED,kBAAkB;YAClB,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC;YAC9C,IAAI,KAAK,EAAE,CAAC;gBACV,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;gBAC5B,IAAI,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;gBAE5B,2BAA2B;gBAC3B,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;oBAC9C,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;oBACnD,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;gBAC7B,CAAC;gBAED,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;YACtB,CAAC;QACH,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;OAGG;IACI,iBAAiB;QACtB,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CACb,mEAAmE;gBACnE,mFAAmF,CACpF,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QAClD,OAAO,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC;IAC9B,CAAC;IAED;;;OAGG;IACI,kBAAkB;QACvB,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CACb,qEAAqE;gBACrE,wDAAwD,CACzD,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,uBAAuB,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QACpD,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;IAC/B,CAAC;IAED;;OAEG;IACI,iBAAiB;QACtB,OAAO,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,CAAC;IACrC,CAAC;IAED;;OAEG;IACI,kBAAkB;QACvB,OAAO,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,QAAQ,CAAC;IAC3C,CAAC;IAED;;OAEG;IACK,sBAAsB,CAAC,KAAqB;QAClD,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,KAAK,CAAC,GAAG,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;YAC1C,OAAO,CAAC,IAAI,CACV,yEAAyE,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,CAC5F,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,YAAY,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,EAAE,CAAC;YACvE,MAAM,IAAI,KAAK,CACb,uCAAuC,KAAK,CAAC,YAAY,KAAK;gBAC9D,0CAA0C,CAC3C,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;QAC5D,CAAC;IACH,CAAC;IAED;;OAEG;IACK,uBAAuB,CAAC,KAAsB;QACpD,MAAM,UAAU,GAAG,kDAAkD,CAAC;QACtE,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;YAClC,MAAM,IAAI,KAAK,CACb,wBAAwB,KAAK,CAAC,KAAK,mCAAmC,CACvE,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAC9E,OAAO,CAAC,IAAI,CACV,uCAAuC,KAAK,CAAC,MAAM,KAAK;gBACxD,2DAA2D,CAC5D,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IAED;;OAEG;IACI,gBAAgB;QACrB,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC;YAC1B,OAAO,iCAAiC,CAAC;QAC3C,CAAC;QAED,OAAO;YACL,kBAAkB;YAClB,UAAU,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE;YACrD,mBAAmB,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,YAAY,EAAE;YACtD,cAAc,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,EAAE;SAC7C,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACf,CAAC;IAED;;OAEG;IACI,iBAAiB;QACtB,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC;YAC3B,OAAO,kCAAkC,CAAC;QAC5C,CAAC;QAED,OAAO;YACL,mBAAmB;YACnB,gBAAgB,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE;YACjE,YAAY,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,EAAE;YACzC,aAAa,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE;SAC5C,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACf,CAAC;IAED;;OAEG;IACK,UAAU,CAAC,MAAc;QAC/B,IAAI,CAAC,MAAM;YAAE,OAAO,SAAS,CAAC;QAC9B,IAAI,MAAM,CAAC,MAAM,IAAI,CAAC;YAAE,OAAO,MAAM,CAAC;QAEtC,MAAM,YAAY,GAAG,CAAC,CAAC;QACvB,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC;QAC5C,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,YAAY,CAAC,CAAC;QACxC,OAAO,GAAG,KAAK,MAAM,GAAG,KAAK,MAAM,CAAC,MAAM,SAAS,CAAC;IACtD,CAAC;IAED;;OAEG;IACI,aAAa,CAAC,MAAkC;QACrD,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,MAAM,CAAC,CAAC;QAEjD,uBAAuB;QACvB,IAAI,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YAC3B,MAAM,MAAM,GAAG,GAAG,OAAO,WAAW,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;YACjD,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YACjC,OAAO,CAAC,GAAG,CAAC,kCAAkC,MAAM,EAAE,CAAC,CAAC;QAC1D,CAAC;QAED,wBAAwB;QACxB,IAAI,eAAe,GAAG,EAAE,CAAC;QACzB,IAAI,YAAY,GAA2B,EAAE,CAAC;QAC9C,IAAI,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YAC3B,eAAe,GAAG,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YACpD,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC,eAAe,CAAC,CAAC;QACpD,CAAC;QAED,8BAA8B;QAC9B,IAAI,MAAM,CAAC,GAAG,EAAE,CAAC;YACf,YAAY,CAAC,gBAAgB,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC;YAC/C,YAAY,CAAC,gBAAgB,GAAG,MAAM,CAAC,GAAG,CAAC,YAAY,CAAC;YACxD,YAAY,CAAC,oBAAoB,GAAG,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC;QACzD,CAAC;QAED,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;YAChB,YAAY,CAAC,cAAc,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC;YACnD,YAAY,CAAC,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC;YAC5C,YAAY,CAAC,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;QAChD,CAAC;QAED,qBAAqB;QACrB,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC;aAC5C,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,IAAI,KAAK,EAAE,CAAC;aACxC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEd,EAAE,CAAC,aAAa,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;QACtD,OAAO,CAAC,GAAG,CAAC,6BAA6B,CAAC,CAAC;QAE3C,+BAA+B;QAC/B,IAAI,CAAC,eAAe,EAAE,CAAC;QAEvB,qBAAqB;QACrB,IAAI,CAAC,WAAW,EAAE,CAAC;IACrB,CAAC;IAED;;OAEG;IACK,eAAe;QACrB,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,YAAY,CAAC,CAAC;QAE7D,IAAI,gBAAgB,GAAG,EAAE,CAAC;QAC1B,IAAI,EAAE,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;YACjC,gBAAgB,GAAG,EAAE,CAAC,YAAY,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;QAC7D,CAAC;QAED,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YACvC,EAAE,CAAC,cAAc,CAAC,aAAa,EAAE,kDAAkD,CAAC,CAAC;YACrF,OAAO,CAAC,GAAG,CAAC,4BAA4B,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC;IAED;;OAEG;IACI,gBAAgB;QACrB,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,cAAc,CAAC,CAAC;QAE7D,MAAM,cAAc,GAAG;;;;;;;;;;;;CAY1B,CAAC;QAEE,EAAE,CAAC,aAAa,CAAC,WAAW,EAAE,cAAc,EAAE,OAAO,CAAC,CAAC;QACvD,OAAO,CAAC,GAAG,CAAC,yCAAyC,CAAC,CAAC;IACzD,CAAC;CACF;AAED,4BAA4B;AAC5B,MAAM,CAAC,MAAM,kBAAkB,GAAG,kBAAkB,CAAC,WAAW,EAAE,CAAC"}

package/dist/core/project-structure-detector.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Project Structure Detector
+ *
+ * Automatically detects project management structure from:
+ * - Existing increments and work items
+ * - Source system metadata (Jira, ADO, GitHub)
+ * - Environment variables
+ *
+ * Supports various hierarchies:
+ * - Jira: Epic → Story → Sub-task
+ * - ADO: Epic → Feature → User Story → Task
+ * - GitHub: Milestone → Issue (or flat Issues)
+ * - Custom: Detected from patterns
+ */
+/**
+ * Hierarchy levels:
+ * - FLAT: No hierarchy (GitHub issues, flat ADO)
+ * - SINGLE_PARENT: Milestone/Feature → Items
+ * - TWO_LEVEL: Epic → Stories → Tasks
+ * - THREE_LEVEL: Initiative → Epic → Feature → Stories
+ */
+export type HierarchyLevel = 'flat' | 'single_parent' | 'two_level' | 'three_level';
+/**
+ * Work item types vary by system
+ */
+export interface WorkItemTypes {
+    topLevel?: string;
+    parentLevel?: string;
+    itemLevel: string;
+    subItemLevel?: string;
+}
+/**
+ * Grouping strategy for RFC organization
+ */
+export type GroupingStrategy = 'by_type' | 'by_parent' | 'by_priority' | 'by_label' | 'flat' | 'custom';
+/**
+ * Project structure configuration
+ */
+export interface ProjectStructure {
+    source: 'jira' | 'ado' | 'github' | 'manual';
+    hierarchyLevel: HierarchyLevel;
+    workItemTypes: WorkItemTypes;
+    groupingStrategy: GroupingStrategy;
+    customGrouping?: (items: any[]) => Record<string, any[]>;
+    epicFieldName?: string;
+    featureFieldName?: string;
+    milestoneFieldName?: string;
+}
+/**
+ * Detected structure from analysis
+ */
+export interface DetectedStructure {
+    structure: ProjectStructure;
+    confidence: number;
+    evidence: string[];
+    sampleIncrements: string[];
+}
+export declare class ProjectStructureDetector {
+    private projectRoot;
+    constructor(projectRoot?: string);
+    /**
+     * Detect project structure with pure auto-detection
+     */
+    detectStructure(): Promise<ProjectStructure>;
+    /**
+     * Auto-detect structure from existing increments
+     */
+    private autoDetectStructure;
+    /**
+     * Analyze increments to detect structure
+     */
+    private analyzeIncrements;
+    /**
+     * Infer work item types from source and hierarchy
+     */
+    private inferWorkItemTypes;
+    /**
+     * Infer grouping strategy from source and hierarchy
+     */
+    private inferGroupingStrategy;
+    /**
+     * Get default structure when no increments exist
+     */
+    private getDefaultStructure;
+    /**
+     * Get structure summary for display
+     */
+    getStructureSummary(structure: ProjectStructure): string;
+    private getHierarchyDescription;
+    private getGroupingDescription;
+}
+//# sourceMappingURL=project-structure-detector.d.ts.map

package/dist/core/project-structure-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-structure-detector.d.ts","sourceRoot":"","sources":["../../src/core/project-structure-detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,eAAe,GAAG,WAAW,GAAG,aAAa,CAAC;AAEpF;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GACxB,SAAS,GACT,WAAW,GACX,aAAa,GACb,UAAU,GACV,MAAM,GACN,QAAQ,CAAC;AAEb;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC7C,cAAc,EAAE,cAAc,CAAC;IAC/B,aAAa,EAAE,aAAa,CAAC;IAC7B,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,KAAK,MAAM,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;IAGzD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,gBAAgB,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED,qBAAa,wBAAwB;IACnC,OAAO,CAAC,WAAW,CAAS;gBAEhB,WAAW,GAAE,MAAsB;IAI/C;;OAEG;IACU,eAAe,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAMzD;;OAEG;YACW,mBAAmB;IA2BjC;;OAEG;YACW,iBAAiB;IA2G/B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAqC1B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAwB7B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAwD3B;;OAEG;IACI,mBAAmB,CAAC,SAAS,EAAE,gBAAgB,GAAG,MAAM;IAO/D,OAAO,CAAC,uBAAuB;IAY/B,OAAO,CAAC,sBAAsB;CAY/B"}

package/dist/core/project-structure-detector.js

@@ -0,0 +1,289 @@
+/**
+ * Project Structure Detector
+ *
+ * Automatically detects project management structure from:
+ * - Existing increments and work items
+ * - Source system metadata (Jira, ADO, GitHub)
+ * - Environment variables
+ *
+ * Supports various hierarchies:
+ * - Jira: Epic → Story → Sub-task
+ * - ADO: Epic → Feature → User Story → Task
+ * - GitHub: Milestone → Issue (or flat Issues)
+ * - Custom: Detected from patterns
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'js-yaml';
+export class ProjectStructureDetector {
+    constructor(projectRoot = process.cwd()) {
+        this.projectRoot = projectRoot;
+    }
+    /**
+     * Detect project structure with pure auto-detection
+     */
+    async detectStructure() {
+        // Auto-detect from existing increments
+        const detected = await this.autoDetectStructure();
+        return detected.structure;
+    }
+    /**
+     * Auto-detect structure from existing increments
+     */
+    async autoDetectStructure() {
+        const incrementsDir = path.join(this.projectRoot, '.specweave', 'increments');
+        if (!fs.existsSync(incrementsDir)) {
+            // No increments yet, use defaults based on source
+            return this.getDefaultStructure();
+        }
+        const increments = fs.readdirSync(incrementsDir)
+            .filter(name => /^\d{4}/.test(name))
+            .slice(0, 5); // Analyze first 5 increments
+        if (increments.length === 0) {
+            return this.getDefaultStructure();
+        }
+        // Analyze increments for patterns
+        const analysis = await this.analyzeIncrements(increments);
+        return {
+            structure: analysis.structure,
+            confidence: analysis.confidence,
+            evidence: analysis.evidence,
+            sampleIncrements: increments
+        };
+    }
+    /**
+     * Analyze increments to detect structure
+     */
+    async analyzeIncrements(increments) {
+        const evidence = [];
+        let hasEpics = false;
+        let hasFeatures = false;
+        let hasMilestones = false;
+        let hasInitiatives = false;
+        let source = 'manual';
+        const workItemTypesSeen = new Set();
+        for (const increment of increments) {
+            const specPath = path.join(this.projectRoot, '.specweave', 'increments', increment, 'spec.md');
+            if (!fs.existsSync(specPath))
+                continue;
+            const content = fs.readFileSync(specPath, 'utf-8');
+            const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+            if (!frontmatterMatch)
+                continue;
+            const frontmatter = yaml.load(frontmatterMatch[1]);
+            // Detect source
+            if (frontmatter.jira) {
+                source = 'jira';
+                evidence.push(`Found Jira metadata in ${increment}`);
+                if (frontmatter.jira.epic_key) {
+                    hasEpics = true;
+                    evidence.push(`Found Epic link: ${frontmatter.jira.epic_key}`);
+                }
+            }
+            if (frontmatter.ado) {
+                source = 'ado';
+                evidence.push(`Found ADO metadata in ${increment}`);
+                if (frontmatter.ado.feature_id) {
+                    hasFeatures = true;
+                    evidence.push(`Found Feature link: ${frontmatter.ado.feature_id}`);
+                }
+                if (frontmatter.ado.epic_id) {
+                    hasEpics = true;
+                    evidence.push(`Found Epic link in ADO`);
+                }
+            }
+            if (frontmatter.github) {
+                source = 'github';
+                evidence.push(`Found GitHub metadata in ${increment}`);
+                if (frontmatter.github.milestone) {
+                    hasMilestones = true;
+                    evidence.push(`Found Milestone: ${frontmatter.github.milestone}`);
+                }
+            }
+            // Analyze work items
+            if (frontmatter.work_items && Array.isArray(frontmatter.work_items)) {
+                frontmatter.work_items.forEach((item) => {
+                    if (item.type) {
+                        workItemTypesSeen.add(item.type);
+                    }
+                });
+            }
+        }
+        // Determine hierarchy level
+        let hierarchyLevel;
+        if (hasInitiatives && hasEpics && hasFeatures) {
+            hierarchyLevel = 'three_level';
+            evidence.push('Detected 3-level hierarchy (Initiative → Epic → Feature → Stories)');
+        }
+        else if (hasEpics || hasFeatures || hasMilestones) {
+            hierarchyLevel = 'two_level';
+            evidence.push(`Detected 2-level hierarchy with ${hasEpics ? 'Epics' : hasFeatures ? 'Features' : 'Milestones'}`);
+        }
+        else if (workItemTypesSeen.size > 0) {
+            hierarchyLevel = 'single_parent';
+            evidence.push('Detected single-level grouping by type');
+        }
+        else {
+            hierarchyLevel = 'flat';
+            evidence.push('Detected flat structure (no hierarchy)');
+        }
+        // Determine work item types
+        const workItemTypes = this.inferWorkItemTypes(source, hierarchyLevel, workItemTypesSeen);
+        // Determine grouping strategy
+        const groupingStrategy = this.inferGroupingStrategy(source, hierarchyLevel, workItemTypesSeen);
+        return {
+            structure: {
+                source,
+                hierarchyLevel,
+                workItemTypes,
+                groupingStrategy
+            },
+            confidence: Math.min(increments.length / 5, 1), // More samples = higher confidence
+            evidence,
+            sampleIncrements: increments
+        };
+    }
+    /**
+     * Infer work item types from source and hierarchy
+     */
+    inferWorkItemTypes(source, hierarchyLevel, typesSeen) {
+        switch (source) {
+            case 'jira':
+                return hierarchyLevel === 'three_level'
+                    ? { topLevel: 'Initiative', parentLevel: 'Epic', itemLevel: 'Story', subItemLevel: 'Sub-task' }
+                    : { parentLevel: 'Epic', itemLevel: 'Story', subItemLevel: 'Sub-task' };
+            case 'ado':
+                if (hierarchyLevel === 'three_level') {
+                    return { topLevel: 'Epic', parentLevel: 'Feature', itemLevel: 'User Story', subItemLevel: 'Task' };
+                }
+                else if (hierarchyLevel === 'two_level') {
+                    return { parentLevel: 'Feature', itemLevel: 'User Story', subItemLevel: 'Task' };
+                }
+                else {
+                    return { itemLevel: 'User Story', subItemLevel: 'Task' };
+                }
+            case 'github':
+                return hierarchyLevel === 'two_level'
+                    ? { parentLevel: 'Milestone', itemLevel: 'Issue' }
+                    : { itemLevel: 'Issue' };
+            default:
+                // Infer from types seen
+                if (typesSeen.has('story')) {
+                    return { parentLevel: 'Epic', itemLevel: 'Story', subItemLevel: 'Task' };
+                }
+                else if (typesSeen.has('issue')) {
+                    return { itemLevel: 'Issue' };
+                }
+                else {
+                    return { itemLevel: 'Item' };
+                }
+        }
+    }
+    /**
+     * Infer grouping strategy from source and hierarchy
+     */
+    inferGroupingStrategy(source, hierarchyLevel, typesSeen) {
+        // If we see story/bug/task types, group by type
+        if (typesSeen.has('story') || typesSeen.has('bug') || typesSeen.has('task')) {
+            return 'by_type';
+        }
+        // If we have parent level (epic, feature, milestone), group by parent
+        if (hierarchyLevel === 'two_level' || hierarchyLevel === 'three_level') {
+            return 'by_parent';
+        }
+        // GitHub typically uses flat or by_label
+        if (source === 'github') {
+            return 'by_label';
+        }
+        // Default to by_type
+        return 'by_type';
+    }
+    /**
+     * Get default structure when no increments exist
+     */
+    getDefaultStructure() {
+        // Try to infer from environment or use sensible defaults
+        const envSource = (process.env.JIRA_DOMAIN ? 'jira' :
+            process.env.AZURE_DEVOPS_ORG ? 'ado' :
+                process.env.GITHUB_REPOSITORY ? 'github' : 'manual');
+        const defaultStructures = {
+            jira: {
+                source: 'jira',
+                hierarchyLevel: 'two_level',
+                workItemTypes: {
+                    parentLevel: 'Epic',
+                    itemLevel: 'Story',
+                    subItemLevel: 'Sub-task'
+                },
+                groupingStrategy: 'by_type'
+            },
+            ado: {
+                source: 'ado',
+                hierarchyLevel: 'two_level',
+                workItemTypes: {
+                    parentLevel: 'Feature',
+                    itemLevel: 'User Story',
+                    subItemLevel: 'Task'
+                },
+                groupingStrategy: 'by_type'
+            },
+            github: {
+                source: 'github',
+                hierarchyLevel: 'two_level',
+                workItemTypes: {
+                    parentLevel: 'Milestone',
+                    itemLevel: 'Issue'
+                },
+                groupingStrategy: 'by_label'
+            },
+            manual: {
+                source: 'manual',
+                hierarchyLevel: 'two_level',
+                workItemTypes: {
+                    parentLevel: 'Feature',
+                    itemLevel: 'Story',
+                    subItemLevel: 'Task'
+                },
+                groupingStrategy: 'by_type'
+            }
+        };
+        return {
+            structure: defaultStructures[envSource],
+            confidence: 0.5,
+            evidence: ['Using default structure based on environment'],
+            sampleIncrements: []
+        };
+    }
+    /**
+     * Get structure summary for display
+     */
+    getStructureSummary(structure) {
+        const hierarchy = this.getHierarchyDescription(structure);
+        const grouping = this.getGroupingDescription(structure.groupingStrategy);
+        return `Source: ${structure.source.toUpperCase()}\nHierarchy: ${hierarchy}\nGrouping: ${grouping}`;
+    }
+    getHierarchyDescription(structure) {
+        const types = structure.workItemTypes;
+        const parts = [];
+        if (types.topLevel)
+            parts.push(types.topLevel);
+        if (types.parentLevel)
+            parts.push(types.parentLevel);
+        parts.push(types.itemLevel);
+        if (types.subItemLevel)
+            parts.push(types.subItemLevel);
+        return parts.join(' → ');
+    }
+    getGroupingDescription(strategy) {
+        const descriptions = {
+            by_type: 'Group by Type (Story, Bug, Task)',
+            by_parent: 'Group by Parent (Epic, Feature, Milestone)',
+            by_priority: 'Group by Priority (P1, P2, P3)',
+            by_label: 'Group by Label/Tag',
+            flat: 'Flat List (No Grouping)',
+            custom: 'Custom Grouping'
+        };
+        return descriptions[strategy];
+    }
+}
+//# sourceMappingURL=project-structure-detector.js.map