specweave 0.8.17 → 0.8.19

package/dist/utils/env-multi-project-parser.js

@@ -0,0 +1,406 @@
+/**
+ * Environment Multi-Project Parser
+ *
+ * Parses comma-separated project lists from .env:
+ * - JIRA_PROJECT_KEYS=BACKEND,FRONTEND,MOBILE
+ * - GITHUB_REPOS=owner/backend-api,owner/frontend-web
+ * - AZURE_DEVOPS_PROJECTS=backend-api,frontend-web
+ *
+ * Auto-creates sync profiles for each project.
+ */
+// ============================================================================
+// Parsing Functions
+// ============================================================================
+/**
+ * Parse comma-separated list from environment variable
+ *
+ * Handles:
+ * - Comma separation
+ * - Whitespace trimming
+ * - Empty values filtering
+ *
+ * @example
+ * parseCommaSeparated("BACKEND, FRONTEND, MOBILE")
+ * // Returns: ["BACKEND", "FRONTEND", "MOBILE"]
+ */
+export function parseCommaSeparated(value) {
+    if (!value) {
+        return [];
+    }
+    return value
+        .split(',')
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0);
+}
+/**
+ * Parse JIRA project keys from .env
+ *
+ * Reads:
+ * - JIRA_PROJECT_KEYS (comma-separated, NEW format)
+ * - JIRA_PROJECT_KEY (single, legacy format)
+ * - JIRA_DOMAIN, JIRA_EMAIL, JIRA_API_TOKEN (shared credentials)
+ *
+ * @returns Array of JIRA project configurations
+ *
+ * @example
+ * // .env:
+ * // JIRA_PROJECT_KEYS=BACKEND,FRONTEND,MOBILE
+ * // JIRA_DOMAIN=mycompany.atlassian.net
+ * // JIRA_EMAIL=user@example.com
+ * // JIRA_API_TOKEN=abc123
+ *
+ * parseJiraProjects()
+ * // Returns: [
+ * //   { projectKey: "BACKEND", domain: "...", email: "...", apiToken: "..." },
+ * //   { projectKey: "FRONTEND", ... },
+ * //   { projectKey: "MOBILE", ... }
+ * // ]
+ */
+export function parseJiraProjects() {
+    const domain = process.env.JIRA_DOMAIN;
+    const email = process.env.JIRA_EMAIL;
+    const apiToken = process.env.JIRA_API_TOKEN;
+    // Missing credentials → return empty array
+    if (!domain || !email || !apiToken) {
+        return [];
+    }
+    // Try new format (JIRA_PROJECT_KEYS - plural)
+    const projectKeysStr = process.env.JIRA_PROJECT_KEYS;
+    if (projectKeysStr) {
+        const projectKeys = parseCommaSeparated(projectKeysStr);
+        return projectKeys.map((projectKey) => ({
+            projectKey,
+            domain,
+            email,
+            apiToken,
+        }));
+    }
+    // Fallback to legacy format (JIRA_PROJECT_KEY - singular)
+    const legacyProjectKey = process.env.JIRA_PROJECT_KEY;
+    if (legacyProjectKey) {
+        return [
+            {
+                projectKey: legacyProjectKey.trim(),
+                domain,
+                email,
+                apiToken,
+            },
+        ];
+    }
+    return [];
+}
+/**
+ * Parse GitHub repositories from .env
+ *
+ * Reads:
+ * - GITHUB_REPOS (comma-separated, format: "owner/repo,owner2/repo2")
+ * - GITHUB_TOKEN (shared credential)
+ *
+ * @returns Array of GitHub repository configurations
+ *
+ * @example
+ * // .env:
+ * // GITHUB_REPOS=myorg/backend-api,myorg/frontend-web
+ * // GITHUB_TOKEN=ghp_abc123
+ *
+ * parseGitHubRepos()
+ * // Returns: [
+ * //   { owner: "myorg", repo: "backend-api", token: "..." },
+ * //   { owner: "myorg", repo: "frontend-web", token: "..." }
+ * // ]
+ */
+export function parseGitHubRepos() {
+    const token = process.env.GITHUB_TOKEN;
+    // Missing token → return empty array
+    if (!token) {
+        return [];
+    }
+    // Parse GITHUB_REPOS (comma-separated "owner/repo" format)
+    const reposStr = process.env.GITHUB_REPOS;
+    if (!reposStr) {
+        return [];
+    }
+    const repos = parseCommaSeparated(reposStr);
+    const configs = [];
+    for (const repo of repos) {
+        // Format: "owner/repo"
+        const parts = repo.split('/');
+        if (parts.length === 2) {
+            configs.push({
+                owner: parts[0].trim(),
+                repo: parts[1].trim(),
+                token,
+            });
+        }
+    }
+    return configs;
+}
+/**
+ * Parse Azure DevOps projects from .env
+ *
+ * Reads:
+ * - AZURE_DEVOPS_PROJECTS (comma-separated)
+ * - AZURE_DEVOPS_ORG (shared organization)
+ * - AZURE_DEVOPS_PAT (shared credential)
+ *
+ * @returns Array of Azure DevOps project configurations
+ *
+ * @example
+ * // .env:
+ * // AZURE_DEVOPS_PROJECTS=backend-api,frontend-web
+ * // AZURE_DEVOPS_ORG=easychamp
+ * // AZURE_DEVOPS_PAT=xyz789
+ *
+ * parseAdoProjects()
+ * // Returns: [
+ * //   { organization: "easychamp", project: "backend-api", pat: "..." },
+ * //   { organization: "easychamp", project: "frontend-web", pat: "..." }
+ * // ]
+ */
+export function parseAdoProjects() {
+    const organization = process.env.AZURE_DEVOPS_ORG;
+    const pat = process.env.AZURE_DEVOPS_PAT;
+    // Missing credentials → return empty array
+    if (!organization || !pat) {
+        return [];
+    }
+    // Try new format (AZURE_DEVOPS_PROJECTS - plural)
+    const projectsStr = process.env.AZURE_DEVOPS_PROJECTS;
+    if (projectsStr) {
+        const projects = parseCommaSeparated(projectsStr);
+        return projects.map((project) => ({
+            organization,
+            project,
+            pat,
+        }));
+    }
+    // Fallback to legacy format (AZURE_DEVOPS_PROJECT - singular)
+    const legacyProject = process.env.AZURE_DEVOPS_PROJECT;
+    if (legacyProject) {
+        return [
+            {
+                organization,
+                project: legacyProject.trim(),
+                pat,
+            },
+        ];
+    }
+    return [];
+}
+/**
+ * Parse all multi-project configurations from .env
+ *
+ * @returns All detected project configurations
+ */
+export function parseMultiProjectEnv() {
+    return {
+        jira: parseJiraProjects(),
+        github: parseGitHubRepos(),
+        ado: parseAdoProjects(),
+    };
+}
+// ============================================================================
+// Sync Profile Generation
+// ============================================================================
+/**
+ * Generate sync profile ID from project identifier
+ *
+ * Format: "{provider}-{project-id}"
+ *
+ * @example
+ * generateProfileId("jira", "BACKEND")
+ * // Returns: "jira-backend"
+ *
+ * @example
+ * generateProfileId("github", "backend-api")
+ * // Returns: "github-backend-api"
+ */
+export function generateProfileId(provider, projectId) {
+    return `${provider}-${projectId.toLowerCase().replace(/[^a-z0-9-]/g, '-')}`;
+}
+/**
+ * Create JIRA sync profile from project configuration
+ */
+export function createJiraSyncProfile(config) {
+    const profileId = generateProfileId('jira', config.projectKey);
+    return {
+        id: profileId,
+        profile: {
+            provider: 'jira',
+            displayName: `JIRA ${config.projectKey}`,
+            description: `Auto-created from JIRA_PROJECT_KEYS (project: ${config.projectKey})`,
+            config: {
+                domain: config.domain,
+                projectKey: config.projectKey,
+                issueType: 'Epic',
+            },
+            timeRange: {
+                default: '1M',
+                max: '3M',
+            },
+            rateLimits: {
+                maxItemsPerSync: 200,
+                warnThreshold: 50,
+            },
+        },
+    };
+}
+/**
+ * Create GitHub sync profile from repository configuration
+ */
+export function createGitHubSyncProfile(config) {
+    const profileId = generateProfileId('github', config.repo);
+    return {
+        id: profileId,
+        profile: {
+            provider: 'github',
+            displayName: `${config.owner}/${config.repo}`,
+            description: `Auto-created from GITHUB_REPOS`,
+            config: {
+                owner: config.owner,
+                repo: config.repo,
+            },
+            timeRange: {
+                default: '1M',
+                max: '6M',
+            },
+            rateLimits: {
+                maxItemsPerSync: 500,
+                warnThreshold: 100,
+            },
+        },
+    };
+}
+/**
+ * Create Azure DevOps sync profile from project configuration
+ */
+export function createAdoSyncProfile(config) {
+    const profileId = generateProfileId('ado', config.project);
+    return {
+        id: profileId,
+        profile: {
+            provider: 'ado',
+            displayName: `${config.organization}/${config.project}`,
+            description: `Auto-created from AZURE_DEVOPS_PROJECTS`,
+            config: {
+                organization: config.organization,
+                project: config.project,
+                workItemType: 'Epic',
+            },
+            timeRange: {
+                default: '1M',
+                max: '1Y',
+            },
+            rateLimits: {
+                maxItemsPerSync: 500,
+                warnThreshold: 100,
+            },
+        },
+    };
+}
+/**
+ * Generate all sync profiles from environment variables
+ *
+ * @returns Array of { id, profile } objects ready to be created
+ *
+ * @example
+ * // .env:
+ * // JIRA_PROJECT_KEYS=BACKEND,FRONTEND
+ * // GITHUB_REPOS=myorg/backend-api
+ *
+ * const profiles = generateSyncProfilesFromEnv();
+ * // Returns: [
+ * //   { id: "jira-backend", profile: { ... } },
+ * //   { id: "jira-frontend", profile: { ... } },
+ * //   { id: "github-backend-api", profile: { ... } }
+ * // ]
+ */
+export function generateSyncProfilesFromEnv() {
+    const envConfig = parseMultiProjectEnv();
+    const profiles = [];
+    // JIRA profiles
+    for (const jiraConfig of envConfig.jira) {
+        profiles.push(createJiraSyncProfile(jiraConfig));
+    }
+    // GitHub profiles
+    for (const githubConfig of envConfig.github) {
+        profiles.push(createGitHubSyncProfile(githubConfig));
+    }
+    // Azure DevOps profiles
+    for (const adoConfig of envConfig.ado) {
+        profiles.push(createAdoSyncProfile(adoConfig));
+    }
+    return profiles;
+}
+// ============================================================================
+// Validation
+// ============================================================================
+/**
+ * Validate JIRA project key format
+ *
+ * Rules:
+ * - 2-10 characters
+ * - Uppercase letters only
+ * - No special characters
+ *
+ * @example
+ * validateJiraProjectKey("BACKEND")  // → true
+ * validateJiraProjectKey("backend")  // → "Must be uppercase"
+ * validateJiraProjectKey("BACK")     // → true
+ * validateJiraProjectKey("B")        // → "Must be 2-10 characters"
+ */
+export function validateJiraProjectKey(key) {
+    if (!key) {
+        return 'Project key is required';
+    }
+    if (!/^[A-Z0-9]+$/.test(key)) {
+        return 'Project key must be uppercase letters and numbers only (e.g., BACKEND, PROJ1)';
+    }
+    if (key.length < 2 || key.length > 10) {
+        return 'Project key must be 2-10 characters';
+    }
+    return true;
+}
+/**
+ * Validate GitHub repo format
+ *
+ * Format: "owner/repo"
+ *
+ * @example
+ * validateGitHubRepo("myorg/backend-api")  // → true
+ * validateGitHubRepo("backend-api")        // → "Must be owner/repo format"
+ */
+export function validateGitHubRepo(repo) {
+    if (!repo) {
+        return 'Repository is required';
+    }
+    const parts = repo.split('/');
+    if (parts.length !== 2) {
+        return 'Repository must be in "owner/repo" format (e.g., myorg/backend-api)';
+    }
+    const [owner, repoName] = parts;
+    if (!owner || !repoName) {
+        return 'Both owner and repo name are required';
+    }
+    if (!/^[a-zA-Z0-9-_.]+$/.test(owner) || !/^[a-zA-Z0-9-_.]+$/.test(repoName)) {
+        return 'Owner and repo name can only contain letters, numbers, hyphens, underscores, and dots';
+    }
+    return true;
+}
+/**
+ * Validate Azure DevOps project name
+ *
+ * @example
+ * validateAdoProject("backend-api")  // → true
+ * validateAdoProject("")             // → "Project name is required"
+ */
+export function validateAdoProject(project) {
+    if (!project) {
+        return 'Project name is required';
+    }
+    if (project.length < 2 || project.length > 64) {
+        return 'Project name must be 2-64 characters';
+    }
+    return true;
+}
+//# sourceMappingURL=env-multi-project-parser.js.map

package/dist/utils/env-multi-project-parser.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specweave",
-  "version": "0.8.17",
+  "version": "0.8.19",
   "description": "Spec-driven development framework for Claude Code. AI-native workflow with living documentation, intelligent agents, and multilingual support (9 languages). Enterprise-grade traceability with permanent specs and temporary increments.",
   "type": "module",
   "main": "dist/index.js",

package/plugins/specweave/hooks/post-first-increment.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# SpecWeave Post-First-Increment Hook
+#
+# Triggers after the first increment is completed
+# Suggests docs-preview plugin for internal documentation
+#
+# NON-INTERACTIVE: Just shows a message (hooks run in background)
+
+set -euo pipefail
+
+# Get project root (where .specweave/ lives)
+PROJECT_ROOT="$(pwd)"
+
+# Check if .specweave directory exists
+if [ ! -d ".specweave" ]; then
+  # Not in SpecWeave project, skip
+  exit 0
+fi
+
+# Check if this is the first increment completion
+# Count completed increments in .specweave/increments/
+COMPLETED_COUNT=0
+if [ -d ".specweave/increments" ]; then
+  # Count directories that have COMPLETION-REPORT.md or completion metadata
+  for inc_dir in .specweave/increments/[0-9][0-9][0-9][0-9]-*/; do
+    if [ -d "$inc_dir" ]; then
+      if [ -f "${inc_dir}reports/COMPLETION-REPORT.md" ] || \
+         [ -f "${inc_dir}COMPLETION-SUMMARY.md" ] || \
+         ([ -f "${inc_dir}metadata.json" ] && grep -q '"status".*"completed"' "${inc_dir}metadata.json" 2>/dev/null); then
+        COMPLETED_COUNT=$((COMPLETED_COUNT + 1))
+      fi
+    fi
+  done
+fi
+
+# Only trigger on first completion
+if [ "$COMPLETED_COUNT" -ne 1 ]; then
+  exit 0
+fi
+
+# Check if docs-preview plugin is already installed
+PLUGIN_INSTALLED=false
+if command -v claude &> /dev/null; then
+  if claude plugin list --installed 2>/dev/null | grep -q "specweave-docs-preview"; then
+    PLUGIN_INSTALLED=true
+  fi
+fi
+
+# If already installed, skip suggestion
+if [ "$PLUGIN_INSTALLED" = true ]; then
+  exit 0
+fi
+
+# Show suggestion (non-interactive message)
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "🎉 Congratulations! You completed your first increment!"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+echo "📚 Preview your documentation in a beautiful UI?"
+echo ""
+echo "The specweave-docs-preview plugin can generate a Docusaurus site from"
+echo "your .specweave/docs/ folder with:"
+echo ""
+echo "   ✓ Auto-generated sidebar from folder structure"
+echo "   ✓ Hot reload (edit markdown, see changes instantly)"
+echo "   ✓ Mermaid diagram rendering"
+echo "   ✓ Priority sorting (Strategy → Specs → Architecture → ...)"
+echo ""
+echo "📦 Install with:"
+echo "   /plugin install specweave-docs-preview"
+echo ""
+echo "🚀 Then launch:"
+echo "   /specweave:docs preview"
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+
+exit 0

package/plugins/specweave/skills/increment-planner/SKILL.md

@@ -526,6 +526,8 @@ created: YYYY-MM-DD
 
 **Purpose**: Analyze spec content to identify required SpecWeave plugins AND check if external PM tool sync is configured.
 
+**⚠️ CRITICAL**: For ALL plugin installations, consult the `plugin-expert` skill for correct syntax. NEVER use `@marketplace` suffix!
+
 **Why This Matters**:
 1. SpecWeave's plugin system enables context efficiency (70%+ reduction) by loading only relevant capabilities
 2. PM tool integration enables automatic sync of increment progress to external systems (GitHub Issues, Jira, Azure DevOps)
@@ -561,25 +563,57 @@ created: YYYY-MM-DD
    - For Claude Code: Check if plugin available via `/plugin list --installed`
    - Skip already-installed plugins
 
-4. **Suggest installation** (if plugins detected):
-   ```
-   🔌 This increment requires additional plugins:
-
-   Required:
-   • specweave-github - GitHub integration (detected: "sync tasks to GitHub issues")
-   • specweave-kubernetes - K8s deployment (detected: "deploy to production cluster")
+4. **🚨 AUTOMATIC PLUGIN INSTALLATION** (if plugins detected):
 
-   Optional:
-   • specweave-diagrams - Architecture diagrams (helpful for "system architecture")
+   **IMPORTANT**: When you detect required plugins, you MUST:
+   - ✅ Proactively offer to install them (not just suggest)
+   - ✅ Explain WHY each plugin is needed (based on detected keywords)
+   - ✅ Show clear install commands
+   - ✅ Remind user that plugins provide expert AI agents and capabilities
 
-   📦 Install plugins:
-   /plugin install specweave-github
-   /plugin install specweave-kubernetes
-   /plugin install specweave-diagrams
-
-   💡 Plugins will auto-activate during implementation!
+   **Output Format**:
+   ```
+   🔌 Detected plugin requirements from spec content:
+
+   REQUIRED (will significantly improve implementation):
+   • specweave-github - GitHub Issues integration
+     Detected: "sync tasks to GitHub issues", "create pull requests"
+     Provides: GitHub sync, PR automation, issue tracking
+     → Without this: Manual GitHub sync required
+
+   • specweave-kubernetes - Kubernetes deployment
+     Detected: "deploy to production cluster", "kubectl apply"
+     Provides: K8s expert agent, Helm chart generation, deployment validation
+     → Without this: Manual K8s configuration, no validation
+
+   OPTIONAL (helpful but not critical):
+   • specweave-diagrams - Architecture diagrams
+     Detected: "system architecture", "component diagram"
+     Provides: Mermaid + C4 diagram generation
+     → Without this: Manual diagram creation
+
+   📦 Install recommended plugins:
+     /plugin install specweave-github
+     /plugin install specweave-kubernetes
+
+   📦 Install optional plugins:
+     /plugin install specweave-diagrams
+
+   💡 Benefits:
+     • Plugins provide specialized AI agents (GitHub expert, K8s expert, etc.)
+     • Skills auto-activate based on context (zero manual invocation)
+     • 70%+ context reduction (only load what you need)
+     • Best practices built-in (from real-world experience)
+
+   Would you like me to wait while you install these plugins? (Recommended)
+   Or shall I continue without them? (Limited capabilities)
    ```
 
+   **User Decision Points**:
+   - If user installs plugins → continue with full capabilities
+   - If user skips → continue but remind about limitations later
+   - NEVER block increment creation (plugins are enhancements, not requirements)
+
 5. **Auto-Sync to PM Tool** (v0.8.0+):
 
    **🚨 CRITICAL: SpecWeave Repo Dog-Food Requirement**:
@@ -619,7 +653,7 @@ created: YYYY-MM-DD
      ⚠️  External PM Tool Configured: GitHub Issues
         Plugin missing: specweave-github
 
-     To enable auto-sync: /plugin install specweave-github@specweave
+     To enable auto-sync: /plugin install specweave-github
      Or continue without PM sync (local-only mode)
      ```
    - **If PM tool not configured**: