swarm-orchestrator 7.0.0-alpha.0

package/dist/src/github-mcp-integrator.js

@@ -0,0 +1,164 @@
+"use strict";
+/**
+ * GitHub MCP Integration
+ * Generates MCP prompts and validates MCP evidence in verification docs
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GitHubMcpIntegrator = void 0;
+const fs = __importStar(require("fs"));
+class GitHubMcpIntegrator {
+    /**
+     * Generate MCP prompt section for agent instructions
+     */
+    static generateMcpPromptSection() {
+        return `
+GitHub Context (MCP) Requirements:
+- Before making decisions, consult GitHub context using available MCP tools
+- Check for: related issues, existing PRs, recent commits, CI workflows
+- In your verification section, include an "MCP Evidence" section with:
+  * What GitHub context you consulted
+  * Specific evidence quoted (issue numbers, PR titles, workflow names, etc.)
+  * How it influenced your decisions
+- Example MCP Evidence format:
+  
+  ## MCP Evidence
+  - Consulted open issues: Found issue #42 "Add user authentication"
+  - Checked existing PRs: No conflicting PRs for auth feature
+  - Reviewed CI workflow: .github/workflows/ci.yml runs tests on push
+  - Decision: Implemented auth to resolve #42, added tests for CI compatibility
+
+Without MCP evidence in your verification, this step will be flagged.
+`.trim();
+    }
+    /**
+     * Generate /delegate prompt section for agent instructions
+     */
+    static generateDelegatePromptSection() {
+        return `
+Pull Request Creation (via /delegate):
+- When your changes are ready, create a PR using the /delegate command
+- The /delegate command will guide you through PR creation
+- Include the resulting PR URL in your verification section
+- Format: "Created PR: https://github.com/owner/repo/pull/123"
+- If /delegate is not available or fails, note this in verification
+
+Example verification with PR:
+  ## Verification
+  - Changed files: src/api.ts, test/api.test.ts
+  - Tests run: npm test (14 passing)
+  - Created PR: https://github.com/owner/repo/pull/123
+`.trim();
+    }
+    /**
+     * Validate MCP evidence in verification.md
+     */
+    static validateMcpEvidence(verificationPath) {
+        const warnings = [];
+        if (!fs.existsSync(verificationPath)) {
+            return {
+                found: false,
+                warnings: ['verification.md not found']
+            };
+        }
+        const content = fs.readFileSync(verificationPath, 'utf-8');
+        // look for MCP evidence section
+        const mcpSectionMatch = content.match(/##\s+MCP\s+Evidence(.*?)(?=\n##|\n$)/is);
+        if (!mcpSectionMatch || !mcpSectionMatch[1]) {
+            warnings.push('No "## MCP Evidence" section found in verification.md');
+            return { found: false, warnings };
+        }
+        const mcpSection = mcpSectionMatch[1].trim();
+        if (mcpSection.length < 50) {
+            warnings.push('MCP Evidence section is too short (< 50 chars)');
+        }
+        // check for specific evidence markers
+        const hasIssueReference = /issue\s+#?\d+|issues:/i.test(mcpSection);
+        const hasPrReference = /PR\s+#?\d+|pull request/i.test(mcpSection);
+        const hasWorkflowReference = /workflow|\.github\/workflows|CI/i.test(mcpSection);
+        const hasCommitReference = /commit|sha/i.test(mcpSection);
+        const hasDecisionStatement = /decision|influenced|based on|considering/i.test(mcpSection);
+        const evidenceCount = [
+            hasIssueReference,
+            hasPrReference,
+            hasWorkflowReference,
+            hasCommitReference
+        ].filter(Boolean).length;
+        if (evidenceCount === 0) {
+            warnings.push('MCP Evidence has no specific GitHub references (issues, PRs, workflows, commits)');
+        }
+        if (!hasDecisionStatement) {
+            warnings.push('MCP Evidence should explain how context influenced decisions');
+        }
+        return {
+            found: true,
+            section: mcpSection,
+            warnings
+        };
+    }
+    /**
+     * Extract PR URLs from verification.md
+     */
+    static extractPrUrls(verificationPath) {
+        if (!fs.existsSync(verificationPath)) {
+            return [];
+        }
+        const content = fs.readFileSync(verificationPath, 'utf-8');
+        // github PR URLs
+        const urlMatches = content.match(/https:\/\/github\.com\/[^\/]+\/[^\/]+\/pull\/\d+/g) || [];
+        // PR references like "PR: #123" or "Created PR #42"
+        const refMatches = content.match(/(?:PR|pull request)\s*:?\s*#(\d+)/gi) || [];
+        const prNumbers = refMatches.map(m => m.match(/#(\d+)/)?.[1]).filter(Boolean);
+        return [...new Set([...urlMatches, ...prNumbers.map(n => `#${n}`)])];
+    }
+    /**
+     * Format MCP evidence for display
+     */
+    static formatMcpEvidenceDisplay(evidence) {
+        if (!evidence.found) {
+            return `⚠ MCP Evidence: NOT FOUND\n${evidence.warnings.map(w => `  - ${w}`).join('\n')}`;
+        }
+        let output = '✓ MCP Evidence: FOUND\n';
+        if (evidence.section) {
+            output += `\n${evidence.section}\n`;
+        }
+        if (evidence.warnings.length > 0) {
+            output += '\n⚠ Warnings:\n';
+            output += evidence.warnings.map(w => `  - ${w}`).join('\n');
+        }
+        return output;
+    }
+}
+exports.GitHubMcpIntegrator = GitHubMcpIntegrator;

package/dist/src/hook-generator.js

@@ -0,0 +1,229 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HookGenerator = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Generates per-step Copilot CLI hook files that enforce scope boundaries
+ * during execution and capture structured evidence in real-time.
+ *
+ * Hooks are written to <workingDir>/.github/hooks/ which the Copilot CLI
+ * SDK auto-loads on session start. Context (toolName, toolArgs, toolResult)
+ * is piped to hook commands via stdin as JSON.
+ */
+class HookGenerator {
+    /**
+     * Generate hooks for a single step execution.
+     * Writes a hook config to <workingDir>/.github/hooks/ and returns
+     * paths needed for evidence parsing after execution.
+     */
+    generateStepHooks(input) {
+        const hooksDir = path.join(input.workingDir, '.github', 'hooks');
+        fs.mkdirSync(hooksDir, { recursive: true });
+        const evidenceDir = path.join(input.runDir, 'evidence');
+        if (!fs.existsSync(evidenceDir)) {
+            fs.mkdirSync(evidenceDir, { recursive: true });
+        }
+        const evidenceLogPath = path.join(evidenceDir, `step-${input.step.stepNumber}.jsonl`);
+        const scopeRules = this.deriveScopeRules(input.agent, input.existingTestFiles);
+        const hookConfig = this.buildHookConfig(scopeRules, evidenceLogPath, input);
+        const hooksFilePath = path.join(hooksDir, `swarm-step-${input.step.stepNumber}.json`);
+        fs.writeFileSync(hooksFilePath, JSON.stringify(hookConfig, null, 2));
+        return { hooksDir, hooksFilePath, evidenceLogPath, scopeRules };
+    }
+    /**
+     * Remove the generated hooks file after step execution.
+     * The evidence log is NOT removed (it lives in the run directory).
+     */
+    cleanupHooks(hooksFileOrDir) {
+        try {
+            const stat = fs.statSync(hooksFileOrDir);
+            if (stat.isDirectory()) {
+                // Legacy path: remove temp directory from old approach
+                fs.rmSync(hooksFileOrDir, { recursive: true, force: true });
+            }
+            else {
+                // Remove the single hooks JSON file we created
+                fs.unlinkSync(hooksFileOrDir);
+            }
+        }
+        catch {
+            // Best-effort cleanup
+        }
+    }
+    /**
+     * Parse an evidence JSONL file into structured entries.
+     */
+    parseEvidenceLog(evidenceLogPath) {
+        if (!fs.existsSync(evidenceLogPath))
+            return [];
+        const content = fs.readFileSync(evidenceLogPath, 'utf8').trim();
+        if (!content)
+            return [];
+        const entries = [];
+        for (const line of content.split('\n')) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                entries.push(JSON.parse(trimmed));
+            }
+            catch {
+                // Skip malformed lines; hooks may produce partial output on kill
+            }
+        }
+        return entries;
+    }
+    /**
+     * Derive scope rules from agent boundaries.
+     * Agent boundaries contain natural-language rules like
+     * "Do not modify frontend components or UI code". These are mapped
+     * to file path patterns for hook enforcement.
+     */
+    deriveScopeRules(agent, existingTestFiles) {
+        const allow = [];
+        const deny = [];
+        for (const scope of agent.scope) {
+            const lower = scope.toLowerCase();
+            if (lower.includes('frontend') || lower.includes('ui') || lower.includes('component')) {
+                allow.push('src/components', 'src/pages', 'src/views', 'public', 'styles', '.css', '.scss', '.html');
+            }
+            if (lower.includes('backend') || lower.includes('server') || lower.includes('api')) {
+                allow.push('src/api', 'src/server', 'src/routes', 'src/middleware', 'server', 'api');
+            }
+            if (lower.includes('test') || lower.includes('quality')) {
+                allow.push('test', 'tests', '__tests__', 'spec', '.test.', '.spec.');
+            }
+            if (lower.includes('ci/cd') || lower.includes('docker') || lower.includes('deployment')) {
+                allow.push('.github', 'Dockerfile', 'docker-compose', '.env', 'deploy');
+            }
+            if (lower.includes('security')) {
+                allow.push('src', 'config', 'package.json');
+            }
+        }
+        for (const boundary of agent.boundaries) {
+            const lower = boundary.toLowerCase();
+            if (lower.includes('frontend') || lower.includes('ui')) {
+                deny.push('src/components', 'src/pages', 'src/views', '.css', '.scss');
+            }
+            if (lower.includes('backend') || lower.includes('server')) {
+                deny.push('src/api', 'src/server', 'src/routes', 'server');
+            }
+            if (lower.includes('database') || lower.includes('schema') || lower.includes('migration')) {
+                deny.push('migrations', 'prisma/schema', 'db/schema');
+            }
+            if (lower.includes('ci/cd') || lower.includes('pipeline') || lower.includes('infrastructure')) {
+                deny.push('.github/workflows', 'Dockerfile');
+            }
+            if (lower.includes('test framework')) {
+                deny.push('jest.config', 'mocha', '.mocharc');
+            }
+        }
+        // Protect pre-existing test files from modification by default.
+        // Reviewer steps are read-only and do not write to any files.
+        // Worker steps must not modify existing tests unless the goal explicitly requires it.
+        const canModifyTests = agent.name === 'reviewer';
+        if (!canModifyTests && existingTestFiles && existingTestFiles.length > 0) {
+            for (const testFile of existingTestFiles) {
+                deny.push(testFile);
+            }
+        }
+        return {
+            allow: [...new Set(allow)],
+            deny: [...new Set(deny)]
+        };
+    }
+    // Scope enforcement via preToolUse hooks. The SDK reads the
+    // permissionDecision field from the hook's JSON stdout. When a file path
+    // matches a deny rule and no allow rule overrides it, the hook outputs
+    // "deny" with a reason. The SDK blocks the tool call and injects the
+    // reason into the agent's context. Violations are also logged to the
+    // evidence file so the verification layer can flag them independently.
+    /**
+     * Build a bash script that reads context JSON from stdin, checks the
+     * file path against deny/allow rules, and either denies the tool call
+     * (via permissionDecision) or approves it. Violations are logged to
+     * the evidence file regardless for verification-layer enforcement.
+     */
+    buildPreToolUseScript(scopeRules, evidenceLogPath, agentName) {
+        const rulesJson = JSON.stringify({ allow: scopeRules.allow, deny: scopeRules.deny });
+        const escapedPath = evidenceLogPath.replace(/'/g, "'\\'");
+        const safeAgent = agentName.replace(/'/g, '');
+        // Node reads context from stdin, checks scope rules, denies out-of-scope tool calls, logs violations
+        return `node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{const ctx=JSON.parse(d);const rules=${rulesJson.replace(/"/g, '\\"')};const p=(ctx.toolArgs||{}).path||(ctx.toolArgs||{}).filePath||'';if(p&&rules.deny.length>0){const denied=rules.deny.some(r=>p.includes(r));if(denied){const allowed=rules.allow.some(r=>p.includes(r));if(!allowed){const rule=rules.deny.find(r=>p.includes(r));const entry={timestamp:new Date().toISOString(),event:'scope_violation',tool:ctx.toolName||'unknown',filePath:p,agentName:'${safeAgent}',boundaryRule:rule};require('fs').appendFileSync('${escapedPath}',JSON.stringify(entry)+'\\n');process.stdout.write(JSON.stringify({permissionDecision:'deny',permissionDecisionReason:'Scope violation: '+p+' is outside agent boundary ('+rule+')'}));return}}}process.stdout.write(JSON.stringify({permissionDecision:'approve'}))}catch(e){process.stdout.write(JSON.stringify({permissionDecision:'approve'}))}})"`;
+    }
+    /**
+     * Build a bash script that reads context JSON from stdin and appends
+     * a structured evidence entry to the JSONL log file.
+     */
+    buildPostToolUseScript(evidenceLogPath) {
+        const escapedPath = evidenceLogPath.replace(/'/g, "'\\''");
+        return `node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{const ctx=JSON.parse(d);const entry={timestamp:new Date().toISOString(),event:'postToolUse',tool:ctx.toolName||'unknown',filePath:(ctx.toolArgs||{}).path||(ctx.toolArgs||{}).filePath,exitCode:ctx.toolResult?ctx.toolResult.exitCode:undefined};require('fs').appendFileSync('${escapedPath}',JSON.stringify(entry)+'\\n')}catch(e){}})"`;
+    }
+    // ---------------------------------------------------------------------------
+    // Private: build complete hook config
+    // ---------------------------------------------------------------------------
+    buildHookConfig(scopeRules, evidenceLogPath, input) {
+        const escapedEvidence = evidenceLogPath.replace(/'/g, "'\\''");
+        return {
+            version: 1,
+            hooks: {
+                sessionStart: [{
+                        type: 'command',
+                        bash: `node -e "const entry={timestamp:new Date().toISOString(),event:'sessionStart',tool:'session',filePath:'${input.stepBranch}'};try{require('fs').appendFileSync('${escapedEvidence}',JSON.stringify(entry)+'\\n')}catch(e){}"`,
+                        timeoutSec: 10
+                    }],
+                preToolUse: [{
+                        type: 'command',
+                        bash: this.buildPreToolUseScript(scopeRules, evidenceLogPath, input.agent.name),
+                        timeoutSec: 10
+                    }],
+                postToolUse: [{
+                        type: 'command',
+                        bash: this.buildPostToolUseScript(evidenceLogPath),
+                        timeoutSec: 10
+                    }],
+                errorOccurred: [{
+                        type: 'command',
+                        bash: `node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{const ctx=JSON.parse(d);const entry={timestamp:new Date().toISOString(),event:'errorOccurred',tool:'error',exitCode:1};require('fs').appendFileSync('${escapedEvidence}',JSON.stringify(entry)+'\\n')}catch(e){}})"`,
+                        timeoutSec: 10
+                    }]
+            }
+        };
+    }
+}
+exports.HookGenerator = HookGenerator;
+exports.default = HookGenerator;

package/dist/src/index.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateURL = exports.StatisticsTracker = exports.URLShortener = exports.load_quality_gates_config = exports.run_quality_gates = exports.PMAgent = exports.RepairAgent = exports.DemoMode = exports.ShareParser = exports.VerifierEngine = exports.SessionExecutor = exports.ConfigLoader = exports.PlanGenerator = exports.SwarmOrchestrator = void 0;
+/**
+ * Swarm Orchestrator - Public API
+ * Import these for programmatic use of the orchestrator.
+ */
+var swarm_orchestrator_1 = require("./swarm-orchestrator");
+Object.defineProperty(exports, "SwarmOrchestrator", { enumerable: true, get: function () { return swarm_orchestrator_1.SwarmOrchestrator; } });
+var plan_generator_1 = require("./plan-generator");
+Object.defineProperty(exports, "PlanGenerator", { enumerable: true, get: function () { return plan_generator_1.PlanGenerator; } });
+var config_loader_1 = require("./config-loader");
+Object.defineProperty(exports, "ConfigLoader", { enumerable: true, get: function () { return config_loader_1.ConfigLoader; } });
+var session_executor_1 = require("./session-executor");
+Object.defineProperty(exports, "SessionExecutor", { enumerable: true, get: function () { return session_executor_1.SessionExecutor; } });
+var verifier_engine_1 = require("./verifier-engine");
+Object.defineProperty(exports, "VerifierEngine", { enumerable: true, get: function () { return verifier_engine_1.VerifierEngine; } });
+var share_parser_1 = require("./share-parser");
+Object.defineProperty(exports, "ShareParser", { enumerable: true, get: function () { return share_parser_1.ShareParser; } });
+var demo_mode_1 = require("./demo-mode");
+Object.defineProperty(exports, "DemoMode", { enumerable: true, get: function () { return demo_mode_1.DemoMode; } });
+var repair_agent_1 = require("./repair-agent");
+Object.defineProperty(exports, "RepairAgent", { enumerable: true, get: function () { return repair_agent_1.RepairAgent; } });
+var pm_agent_1 = require("./pm-agent");
+Object.defineProperty(exports, "PMAgent", { enumerable: true, get: function () { return pm_agent_1.PMAgent; } });
+var quality_gates_1 = require("./quality-gates");
+Object.defineProperty(exports, "run_quality_gates", { enumerable: true, get: function () { return quality_gates_1.run_quality_gates; } });
+Object.defineProperty(exports, "load_quality_gates_config", { enumerable: true, get: function () { return quality_gates_1.load_quality_gates_config; } });
+var url_shortener_1 = require("./url-shortener");
+Object.defineProperty(exports, "URLShortener", { enumerable: true, get: function () { return url_shortener_1.URLShortener; } });
+Object.defineProperty(exports, "StatisticsTracker", { enumerable: true, get: function () { return url_shortener_1.StatisticsTracker; } });
+Object.defineProperty(exports, "validateURL", { enumerable: true, get: function () { return url_shortener_1.validateURL; } });
+__exportStar(require("./verification"), exports);