swarm-orchestrator 7.0.0-alpha.0

package/dist/src/cli/usage.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.showUsage = showUsage;
+function showUsage() {
+    console.log(`
+Swarm Orchestrator - Falsification and Audit-Ready Orchestration for AI Coding Agents
+
+Usage:
+  swarm bootstrap <path(s)> "Goal"       Deep analysis and plan generation (multi-repo)
+  swarm plan <goal>                      Generate intelligent plan
+  swarm plan --copilot <goal>            Generate Copilot CLI prompt for planning
+  swarm plan import <runid> <transcript> Parse plan from Copilot /share transcript
+  swarm execute <planfile>               Execute a saved plan step-by-step
+  swarm swarm <planfile>                 Execute plan with verified branch/worktree workflow (analyzer-gated concurrency)
+  swarm run --goal "description"          Plan + execute in one step (convenience)
+  swarm quick "task"                     Quick-fix mode for simple single-agent tasks
+  swarm demo <scenario>                  Run pre-configured demo scenario
+  swarm demo-fast                        Fast 2-step demo (alias for: swarm demo demo-fast)
+  swarm demo list                        List available demo scenarios
+  swarm gates [path]                     Run quality gates on a repo (default: cwd)
+  swarm status <execid>                  Show execution status
+  swarm templates                        List available plan templates
+  swarm share import <runid> <step> <agent> <path>
+                                         Import /share transcript for a step
+  swarm share context <runid> <step>     Show prior context for a step
+  swarm audit <session-id>               Generate Markdown audit report for a session
+  swarm metrics <session-id>             Show metrics summary for a session
+  swarm agents export [--output-dir dir] Export agents as .agent.md from execution history
+  swarm use <recipe> [--param k=v ...]   Execute a pre-built recipe (see: swarm recipes)
+  swarm recipes                          List available recipes
+  swarm recipe-info <name>               Show recipe details and parameters
+  swarm report <run-id>                  Generate structured run report from artifacts
+  swarm attest verify <commit>           Verify swarm attestation git note
+  swarm --help                           Show this help message
+
+Flags:
+  --delegate       Instruct agents to use /delegate for PR creation
+  --mcp            Require MCP evidence from GitHub context in verification
+  --model          Specify model for sessions (e.g., claude-sonnet-4.5)
+  --resume <id>    Resume a previously paused/failed swarm session
+  --agent          Specify agent for quick-fix mode
+  --skip-verify    Skip verification in quick-fix mode (faster)
+  --confirm-deploy Enable opt-in deployment for deployment steps (vercel, netlify)
+  --no-quality-gates Disable quality gates (swarm mode)
+  --pm               Run PM agent plan review before swarm execution
+  --strict-isolation Force per-task branch isolation, transcript-only context
+  --lean             Enable Delta Context Engine (reuse prior KB patterns)
+  --useInnerFleet    Prefix prompts with /fleet for inner sub-agent dispatch
+  --wrap-fleet       Enable /fleet prefix on all step prompts (alias for --useInnerFleet)
+  --cost-estimate-only Run plan generation and cost estimation, print result, exit
+  --max-premium-requests <n> Abort if estimated premium requests exceed budget
+  --max-retries <n>    Max retry attempts for queued and repair retries (default 3)
+  --quality-gates-config <path> Path to quality gates YAML (default: config/quality-gates.yaml)
+  --quality-gates-out <dir>    Where to write gate reports (default: <runDir>/quality-gates)
+  --pr <auto|review>   Create PRs instead of direct merge (auto: merge on pass, review: wait for approval)
+  --owasp-report       Generate OWASP ASI compliance report after verification
+  --tool <name>        Agent tool: copilot, claude-code, codex, claude-code-teams
+  --target <dir>       Run execution in specified directory instead of cwd (alias: --dir)
+  --hooks              Enable per-step hook injection for scope enforcement (default: on)
+  --no-hooks           Disable hook injection for debugging
+  --verbose            Enable debug-level logging
+  --output json        Print machine-readable JSON for supported commands
+  --yes, -y            Skip cost confirmation prompt (auto-approve)
+
+Examples:
+  swarm demo-fast
+  swarm plan "Build a REST API for user management"
+  swarm plan --output json "Build a REST API for user management"
+  swarm swarm plan.json --model claude-opus-4.5 --verbose
+  swarm metrics <session-id> --output json
+`);
+}

package/dist/src/cli.js

@@ -0,0 +1,217 @@
+#!/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 __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.generatePlan = void 0;
+exports.main = main;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const flags_1 = require("./cli/flags");
+const logger_1 = require("./logger");
+const presenter_1 = require("./presenter");
+const startupArgs = process.argv.slice(2);
+// User-facing commands enable a clean presenter surface by default:
+// pretty-mode hides `[scope]` prefixes, diagnostic logger output is routed to
+// stderr, and --quiet suppresses everything except errors and the result line.
+// `--verbose` keeps the legacy diagnostic-on-stdout shape for developers.
+const USER_FACING_COMMANDS = new Set(['run', 'swarm', 'quick', 'demo', 'demo-fast', 'bootstrap']);
+const firstNonFlag = startupArgs.find((a) => !a.startsWith('-'));
+const isUserFacingCommand = firstNonFlag ? USER_FACING_COMMANDS.has(firstNonFlag) : false;
+const isVerbose = startupArgs.includes('--verbose');
+const isQuiet = startupArgs.includes('--quiet') || startupArgs.includes('-q');
+(0, logger_1.configureLogger)({
+    level: isQuiet ? 'warn' : (isVerbose ? 'debug' : 'info'),
+    outputFormat: (0, flags_1.parseOutputFormat)(startupArgs),
+    // Diagnostic output (info/debug/trace) routes to stderr when the presenter
+    // owns stdout. Without pretty mode (developer / non-user-facing commands),
+    // diagnostics keep flowing to stdout so tooling that scrapes stdout works.
+    diagnosticsToStderr: isUserFacingCommand && !isVerbose,
+});
+if (isUserFacingCommand && !isVerbose) {
+    (0, logger_1.setPrettyMode)(true);
+}
+(0, presenter_1.configurePresenter)({ quiet: isQuiet });
+const logger = (0, logger_1.getLogger)('cli');
+/**
+ * Parse a single .env file and set any variables not already in process.env.
+ * Supports KEY=value, KEY="value", KEY='value', and `export KEY=value`.
+ * Skips blank lines and comments. No external dependencies.
+ */
+function parseDotenvFile(filePath) {
+    if (!fs.existsSync(filePath))
+        return;
+    const content = fs.readFileSync(filePath, 'utf-8');
+    logger.debug(`loading env file ${filePath}`);
+    for (const raw of content.split('\n')) {
+        const line = raw.trim();
+        if (!line || line.startsWith('#'))
+            continue;
+        const stripped = line.startsWith('export ') ? line.slice(7) : line;
+        const eqIndex = stripped.indexOf('=');
+        if (eqIndex === -1)
+            continue;
+        const key = stripped.slice(0, eqIndex).trim();
+        let value = stripped.slice(eqIndex + 1).trim();
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        if (process.env[key] === undefined) {
+            process.env[key] = value;
+        }
+    }
+}
+/**
+ * Load .env from multiple locations so API keys are found regardless
+ * of which target repo the user runs the command from.
+ *
+ * Search order (first match for a given key wins):
+ *   1. cwd (the target project directory)
+ *   2. The orchestrator's own install directory (where cli.js lives)
+ *   3. The user's home directory (~/.env) as a last-resort fallback
+ */
+function loadDotenv() {
+    const candidates = [
+        path.resolve(process.cwd(), '.env'),
+    ];
+    // __dirname at runtime is dist/src/, so two levels up reaches the
+    // project root where .env and package.json live.
+    const orchestratorRoot = path.resolve(__dirname, '..', '..');
+    const orchestratorEnv = path.join(orchestratorRoot, '.env');
+    if (orchestratorEnv !== candidates[0]) {
+        candidates.push(orchestratorEnv);
+    }
+    const homeEnv = path.join(process.env.HOME || process.env.USERPROFILE || '', '.env');
+    if (homeEnv && !candidates.includes(homeEnv)) {
+        candidates.push(homeEnv);
+    }
+    for (const envPath of candidates) {
+        parseDotenvFile(envPath);
+    }
+}
+loadDotenv();
+const index_1 = require("./cli/index");
+Object.defineProperty(exports, "generatePlan", { enumerable: true, get: function () { return index_1.generatePlan; } });
+async function main() {
+    const args = (0, flags_1.normalizeLeadingGlobalFlags)(process.argv.slice(2));
+    if (args.length === 0) {
+        (0, index_1.showUsage)();
+        return;
+    }
+    const command = args[0];
+    let exitCode = 0;
+    try {
+        switch (command) {
+            case 'demo-fast':
+                exitCode = await (0, index_1.handleDemoCommand)(['demo', 'demo-fast', ...args.slice(1)]);
+                break;
+            case 'gates':
+                exitCode = await (0, index_1.handleGatesCommand)(args.slice(1));
+                break;
+            case 'quick':
+                exitCode = await (0, index_1.handleQuickCommand)(args);
+                break;
+            case 'bootstrap':
+                exitCode = await (0, index_1.handleBootstrapCommand)(args);
+                break;
+            case 'plan':
+                exitCode = await (0, index_1.handlePlanCommand)(args);
+                break;
+            case 'execute':
+                exitCode = await (0, index_1.handleExecuteCommand)(args);
+                break;
+            case 'status':
+                exitCode = await (0, index_1.handleStatusCommand)(args);
+                break;
+            case 'swarm':
+                exitCode = await (0, index_1.handleSwarmCommand)(args);
+                break;
+            case 'demo':
+                exitCode = await (0, index_1.handleDemoCommand)(args);
+                break;
+            case 'templates':
+                exitCode = await (0, index_1.handleTemplatesCommand)();
+                break;
+            case '--help':
+            case '-h':
+                (0, index_1.showUsage)();
+                break;
+            case 'share':
+                exitCode = await (0, index_1.handleShareCommand)(args);
+                break;
+            case 'audit':
+                exitCode = await (0, index_1.handleAuditCommand)(args);
+                break;
+            case 'metrics':
+                exitCode = await (0, index_1.handleMetricsCommand)(args);
+                break;
+            case 'run':
+                exitCode = await (0, index_1.handleRunCommand)(args);
+                break;
+            case 'report':
+                exitCode = await (0, index_1.handleReportCommand)(args);
+                break;
+            case 'agents':
+                exitCode = await (0, index_1.handleAgentsCommand)(args);
+                break;
+            case 'attest':
+                exitCode = await (0, index_1.handleAttestCommand)(args);
+                break;
+            case 'use':
+                exitCode = await (0, index_1.handleUseCommand)(args);
+                break;
+            case 'recipes':
+                exitCode = (0, index_1.handleRecipesCommand)();
+                break;
+            case 'recipe-info':
+                exitCode = (0, index_1.handleRecipeInfoCommand)(args);
+                break;
+            default:
+                logger.error(`Unknown command: ${command}\n`);
+                (0, index_1.showUsage)();
+                exitCode = 1;
+        }
+    }
+    catch (error) {
+        logger.error('Fatal error:', error instanceof Error ? error.message : String(error));
+        exitCode = 1;
+    }
+    if (exitCode !== 0) {
+        process.exit(exitCode);
+    }
+}
+if (require.main === module) {
+    main();
+}

package/dist/src/commit-pattern-detector.js

@@ -0,0 +1,143 @@
+"use strict";
+/**
+ * Commit Pattern Detector
+ *
+ * Analyzes git commit patterns to detect anti-patterns like:
+ * - Generic/vague messages
+ * - Repetitive patterns
+ * - Single-commit dumps
+ * - Non-incremental commits
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommitPatternDetector = void 0;
+/**
+ * Generic/vague message patterns that indicate low quality
+ */
+const GENERIC_PATTERNS = [
+    /^update/i,
+    /^fix$/i,
+    /^fix bug/i,
+    /^changes$/i,
+    /^wip$/i,
+    /^work in progress/i,
+    /^temp$/i,
+    /^temporary/i,
+    /^misc/i,
+    /^various/i,
+    /^stuff$/i,
+    /^code$/i,
+    /^update code/i,
+    /^fix code/i,
+    /^fix issue/i,
+    /^address.*feedback/i,
+    /^pr feedback/i,
+    /^refactor$/i,
+    /^cleanup$/i,
+    /^done$/i,
+    /^complete$/i
+];
+/**
+ * Detects commit anti-patterns in a branch's history
+ */
+class CommitPatternDetector {
+    /**
+     * Analyze commit patterns for quality
+     */
+    analyzeCommits(commits) {
+        if (commits.length === 0) {
+            return {
+                hasAntiPatterns: false,
+                warnings: [],
+                score: 100,
+                details: {
+                    genericMessages: 0,
+                    repetitivePatterns: 0,
+                    singleCommitDump: false,
+                    averageFilesPerCommit: 0,
+                    commitCount: 0
+                }
+            };
+        }
+        const warnings = [];
+        let score = 100;
+        // Check for generic messages
+        const genericCount = commits.filter(c => GENERIC_PATTERNS.some(pattern => pattern.test(c.message))).length;
+        if (genericCount > 0) {
+            warnings.push(`Found ${genericCount} generic/vague commit message(s)`);
+            score -= genericCount * 15;
+        }
+        // Check for repetitive patterns (same message multiple times)
+        const messageFrequency = new Map();
+        for (const commit of commits) {
+            const normalized = commit.message.toLowerCase().trim();
+            messageFrequency.set(normalized, (messageFrequency.get(normalized) || 0) + 1);
+        }
+        const repetitiveCount = Array.from(messageFrequency.values()).filter(count => count > 2).length;
+        if (repetitiveCount > 0) {
+            warnings.push(`Found ${repetitiveCount} repetitive commit message pattern(s)`);
+            score -= repetitiveCount * 20;
+        }
+        // Check for single-commit dump (one commit with many files)
+        const singleCommitDump = commits.length === 1 && commits[0].files.length > 5;
+        if (singleCommitDump) {
+            warnings.push('Single-commit dump detected (one commit with many files)');
+            score -= 30;
+        }
+        // Check for non-incremental work (too many files per commit on average)
+        const totalFiles = commits.reduce((sum, c) => sum + c.files.length, 0);
+        const avgFilesPerCommit = totalFiles / commits.length;
+        if (avgFilesPerCommit > 8 && commits.length > 1) {
+            warnings.push(`High files-per-commit average (${avgFilesPerCommit.toFixed(1)}), suggests non-incremental work`);
+            score -= 15;
+        }
+        // Check for too few commits given file count
+        if (commits.length === 1 && totalFiles > 3) {
+            warnings.push('Too few commits for amount of work (should break into logical chunks)');
+            score -= 20;
+        }
+        // Ensure score stays in 0-100 range
+        score = Math.max(0, Math.min(100, score));
+        return {
+            hasAntiPatterns: warnings.length > 0,
+            warnings,
+            score,
+            details: {
+                genericMessages: genericCount,
+                repetitivePatterns: repetitiveCount,
+                singleCommitDump,
+                averageFilesPerCommit: parseFloat(avgFilesPerCommit.toFixed(1)),
+                commitCount: commits.length
+            }
+        };
+    }
+    /**
+     * Check if a single commit message is problematic
+     */
+    isGenericMessage(message) {
+        return GENERIC_PATTERNS.some(pattern => pattern.test(message));
+    }
+    /**
+     * Get suggestions for improving commit quality
+     */
+    getSuggestions(result) {
+        const suggestions = [];
+        if (result.details.genericMessages > 0) {
+            suggestions.push('Use specific, descriptive commit messages (e.g., "add user authentication API" not "update code")');
+        }
+        if (result.details.repetitivePatterns > 0) {
+            suggestions.push('Vary commit messages to reflect different work done');
+        }
+        if (result.details.singleCommitDump) {
+            suggestions.push('Break work into multiple logical commits (e.g., separate commits for API, tests, docs)');
+        }
+        if (result.details.averageFilesPerCommit > 8) {
+            suggestions.push('Make smaller, more focused commits (aim for 2-5 files per commit)');
+        }
+        if (result.score < 70) {
+            suggestions.push('Review git commit guidelines in your agent instructions for examples');
+        }
+        return suggestions;
+    }
+}
+exports.CommitPatternDetector = CommitPatternDetector;
+exports.default = CommitPatternDetector;

package/dist/src/commit-quality-analyzer.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyzeCommitQuality = analyzeCommitQuality;
+const commit_pattern_detector_1 = require("./commit-pattern-detector");
+const logger_1 = require("./logger");
+const logger = (0, logger_1.getLogger)('commit-quality');
+async function analyzeCommitQuality(commits, stepNumber, agentName) {
+    if (commits.length === 0)
+        return;
+    const detector = new commit_pattern_detector_1.CommitPatternDetector();
+    // Convert to CommitMessage format; parsed commits may carry extra
+    // fields (timestamp, files) beyond the ShareIndex schema
+    const commitMessages = commits.map(c => {
+        const extra = c;
+        return {
+            hash: c.sha || 'unknown',
+            message: c.message || '',
+            timestamp: extra.timestamp ? new Date(extra.timestamp) : new Date(),
+            files: extra.files || []
+        };
+    });
+    const result = detector.analyzeCommits(commitMessages);
+    // Surface anti-patterns; suppress the "all good" announcement so passing
+    // steps stay quiet and the live status block carries the success signal.
+    if (result.hasAntiPatterns) {
+        logger.warn(`  commit-quality warnings · step ${stepNumber} (${agentName}) · score ${result.score}/100`);
+        result.warnings.forEach(warning => {
+            logger.warn(`    - ${warning}`);
+        });
+        const suggestions = detector.getSuggestions(result);
+        if (suggestions.length > 0) {
+            logger.warn(`    suggestions:`);
+            suggestions.forEach(suggestion => {
+                logger.warn(`      - ${suggestion}`);
+            });
+        }
+    }
+}