@ai-sdlc/orchestrator 0.1.0

package/dist/notifications/notification-router.js

@@ -0,0 +1,206 @@
+/**
+ * Notification router — dispatches pipeline events to configured messengers.
+ *
+ * Routes events like pipeline-start, gate-failure, agent-complete, pr-created
+ * to one or more Messenger implementations with filtering and template rendering.
+ */
+// ── Default Templates ────────────────────────────────────────────────
+const DEFAULT_TEMPLATES = {
+    'pipeline-start': {
+        title: 'Pipeline Started',
+        body: 'Pipeline run {runId} started for issue #{issueNumber}',
+    },
+    'pipeline-complete': {
+        title: 'Pipeline Completed',
+        body: 'Pipeline run {runId} completed successfully. PR: {prUrl}',
+    },
+    'pipeline-failed': {
+        title: 'Pipeline Failed',
+        body: 'Pipeline run {runId} failed: {error}',
+    },
+    'gate-pass': {
+        title: 'Gate Passed',
+        body: 'Quality gate "{gateName}" passed for issue #{issueNumber}',
+    },
+    'gate-failure': {
+        title: 'Gate Failed',
+        body: 'Quality gate "{gateName}" failed: {details}',
+    },
+    'agent-start': {
+        title: 'Agent Started',
+        body: 'Agent {agentName} started working on issue #{issueNumber}',
+    },
+    'agent-complete': {
+        title: 'Agent Completed',
+        body: 'Agent {agentName} completed. Files changed: {filesChanged}',
+    },
+    'agent-failed': {
+        title: 'Agent Failed',
+        body: 'Agent {agentName} failed: {error}',
+    },
+    'pr-created': {
+        title: 'PR Created',
+        body: 'Pull request created: {prUrl}',
+    },
+    'approval-required': {
+        title: 'Approval Required',
+        body: 'Issue #{issueNumber} requires approval (tier: {tier})',
+    },
+    promotion: {
+        title: 'Agent Promoted',
+        body: 'Agent {agentName} promoted from level {fromLevel} to {toLevel}',
+    },
+    demotion: {
+        title: 'Agent Demoted',
+        body: 'Agent {agentName} demoted from level {fromLevel} to {toLevel}: {reason}',
+    },
+    'cost-alert': {
+        title: 'Cost Alert',
+        body: 'Budget utilization at {utilization}% ({spent}/{budget} USD)',
+    },
+    'deploy-start': {
+        title: 'Deployment Started',
+        body: 'Deploying {version} to {environment} via {target}',
+    },
+    'deploy-complete': {
+        title: 'Deployment Complete',
+        body: 'Version {version} deployed to {environment}. URL: {url}',
+    },
+    'deploy-failed': {
+        title: 'Deployment Failed',
+        body: 'Deployment of {version} to {environment} failed: {error}',
+    },
+    'rollout-progressing': {
+        title: 'Rollout Progressing',
+        body: 'Rollout at {weightPercent}% (step {step}). Error rate: {errorRate}%, P95: {latencyP95}ms',
+    },
+    'rollout-complete': {
+        title: 'Rollout Complete',
+        body: 'Rollout of {version} to {environment} completed at 100%',
+    },
+    'rollout-rollback': {
+        title: 'Rollout Rolled Back',
+        body: 'Rollout of {version} to {environment} rolled back: {reason}',
+    },
+};
+// ── Router ───────────────────────────────────────────────────────────
+export class NotificationRouter {
+    routes = [];
+    templates = new Map();
+    activeThreads = new Map(); // route+issue -> threadId
+    constructor(customTemplates) {
+        // Initialize with default templates
+        for (const [key, value] of Object.entries(DEFAULT_TEMPLATES)) {
+            this.templates.set(key, value);
+        }
+        // Override with custom templates
+        if (customTemplates) {
+            for (const [key, value] of Object.entries(customTemplates)) {
+                if (value)
+                    this.templates.set(key, value);
+            }
+        }
+    }
+    /**
+     * Add a notification route.
+     */
+    addRoute(route) {
+        this.routes.push(route);
+    }
+    /**
+     * Remove a route by name.
+     */
+    removeRoute(name) {
+        this.routes = this.routes.filter((r) => r.name !== name);
+    }
+    /**
+     * Dispatch a pipeline event to all matching routes.
+     */
+    async dispatch(event) {
+        const matchingRoutes = this.routes.filter((route) => this.matchesRoute(route, event));
+        const promises = matchingRoutes.map((route) => this.sendToRoute(route, event).catch((err) => {
+            // Non-blocking: log but don't fail the pipeline
+            console.error(`Notification route "${route.name}" failed:`, err);
+        }));
+        await Promise.all(promises);
+    }
+    /**
+     * Get the count of configured routes.
+     */
+    get routeCount() {
+        return this.routes.length;
+    }
+    // ── Internal ─────────────────────────────────────────────────────
+    matchesRoute(route, event) {
+        // Check event type filter
+        if (route.events && route.events.length > 0 && !route.events.includes(event.type)) {
+            return false;
+        }
+        // Check minimum severity
+        if (route.minSeverity) {
+            const severityOrder = { info: 0, warning: 1, error: 2 };
+            const eventSeverity = event.severity ?? this.defaultSeverity(event.type);
+            if (severityOrder[eventSeverity] < severityOrder[route.minSeverity]) {
+                return false;
+            }
+        }
+        return true;
+    }
+    async sendToRoute(route, event) {
+        const template = this.templates.get(event.type) ?? {
+            title: event.type,
+            body: JSON.stringify(event.data),
+        };
+        const rendered = this.renderTemplate(template, event.data);
+        const severity = event.severity ?? this.defaultSeverity(event.type);
+        if (route.useThreads) {
+            const threadKey = `${route.name}:${event.data.issueNumber ?? 'global'}`;
+            const existingThread = this.activeThreads.get(threadKey);
+            if (existingThread) {
+                await route.messenger.postUpdate(existingThread, `**${rendered.title}**\n${rendered.body}`);
+            }
+            else {
+                const thread = await route.messenger.createThread({
+                    channel: route.channel,
+                    title: rendered.title,
+                    message: rendered.body,
+                });
+                this.activeThreads.set(threadKey, thread.id);
+            }
+        }
+        else {
+            await route.messenger.sendNotification({
+                channel: route.channel,
+                message: `**${rendered.title}**\n${rendered.body}`,
+                severity,
+            });
+        }
+    }
+    renderTemplate(template, data) {
+        let title = template.title;
+        let body = template.body;
+        for (const [key, value] of Object.entries(data)) {
+            const placeholder = `{${key}}`;
+            title = title.replaceAll(placeholder, String(value));
+            body = body.replaceAll(placeholder, String(value));
+        }
+        return { title, body };
+    }
+    defaultSeverity(type) {
+        switch (type) {
+            case 'pipeline-failed':
+            case 'agent-failed':
+            case 'gate-failure':
+            case 'deploy-failed':
+                return 'error';
+            case 'approval-required':
+            case 'demotion':
+            case 'cost-alert':
+            case 'rollout-rollback':
+                return 'warning';
+            default:
+                return 'info';
+        }
+    }
+}
+//# sourceMappingURL=notification-router.js.map

package/dist/notifications/slack-messenger.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Slack Messenger — implements the Messenger interface using Slack Web API.
+ *
+ * Design decision D5: Uses chat.postMessage via Web API.
+ */
+import type { Messenger, NotificationInput, ThreadInput, Thread } from '@ai-sdlc/reference';
+export interface SlackConfig {
+    /** Slack Bot OAuth token (xoxb-...). */
+    token: string;
+    /** Base URL for Slack API. Defaults to https://slack.com/api. */
+    apiUrl?: string;
+    /** Default channel for notifications (can be overridden per message). */
+    defaultChannel?: string;
+}
+export declare class SlackMessenger implements Messenger {
+    private config;
+    private apiUrl;
+    constructor(config: SlackConfig);
+    sendNotification(input: NotificationInput): Promise<void>;
+    createThread(input: ThreadInput): Promise<Thread>;
+    postUpdate(threadId: string, message: string): Promise<void>;
+    private postMessage;
+    private callAPI;
+    private severityIcon;
+}
+//# sourceMappingURL=slack-messenger.d.ts.map

package/dist/notifications/slack-messenger.js

@@ -0,0 +1,69 @@
+/**
+ * Slack Messenger — implements the Messenger interface using Slack Web API.
+ *
+ * Design decision D5: Uses chat.postMessage via Web API.
+ */
+export class SlackMessenger {
+    config;
+    apiUrl;
+    constructor(config) {
+        this.config = config;
+        this.apiUrl = config.apiUrl ?? 'https://slack.com/api';
+    }
+    async sendNotification(input) {
+        const channel = input.channel || this.config.defaultChannel;
+        if (!channel)
+            throw new Error('No channel specified for Slack notification');
+        const icon = this.severityIcon(input.severity);
+        await this.postMessage(channel, `${icon} ${input.message}`);
+    }
+    async createThread(input) {
+        const channel = input.channel || this.config.defaultChannel;
+        if (!channel)
+            throw new Error('No channel specified for Slack thread');
+        const response = await this.postMessage(channel, `*${input.title}*\n\n${input.message}`);
+        return {
+            id: response.ts ?? '',
+            url: `https://slack.com/archives/${response.channel}/p${response.ts?.replace('.', '')}`,
+        };
+    }
+    async postUpdate(threadId, message) {
+        const channel = this.config.defaultChannel;
+        if (!channel)
+            throw new Error('No default channel for thread update');
+        await this.callAPI('chat.postMessage', {
+            channel,
+            text: message,
+            thread_ts: threadId,
+        });
+    }
+    async postMessage(channel, text) {
+        return this.callAPI('chat.postMessage', { channel, text });
+    }
+    async callAPI(method, body) {
+        const res = await fetch(`${this.apiUrl}/${method}`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json; charset=utf-8',
+                Authorization: `Bearer ${this.config.token}`,
+            },
+            body: JSON.stringify(body),
+        });
+        const data = (await res.json());
+        if (!data.ok) {
+            throw new Error(`Slack API error: ${data.error ?? 'unknown'}`);
+        }
+        return data;
+    }
+    severityIcon(severity) {
+        switch (severity) {
+            case 'error':
+                return ':red_circle:';
+            case 'warning':
+                return ':warning:';
+            default:
+                return ':information_source:';
+        }
+    }
+}
+//# sourceMappingURL=slack-messenger.js.map

package/dist/notifications/teams-messenger.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Microsoft Teams Messenger — implements the Messenger interface using incoming webhooks.
+ *
+ * Design decision D5: Uses incoming webhook URLs for simplicity.
+ */
+import type { Messenger, NotificationInput, ThreadInput, Thread } from '@ai-sdlc/reference';
+export interface TeamsConfig {
+    /** Incoming webhook URL. */
+    webhookUrl: string;
+}
+export declare class TeamsMessenger implements Messenger {
+    private config;
+    constructor(config: TeamsConfig);
+    sendNotification(input: NotificationInput): Promise<void>;
+    createThread(input: ThreadInput): Promise<Thread>;
+    postUpdate(threadId: string, message: string): Promise<void>;
+    private buildCard;
+    private postWebhook;
+    private severityIcon;
+}
+//# sourceMappingURL=teams-messenger.d.ts.map

package/dist/notifications/teams-messenger.js

@@ -0,0 +1,85 @@
+/**
+ * Microsoft Teams Messenger — implements the Messenger interface using incoming webhooks.
+ *
+ * Design decision D5: Uses incoming webhook URLs for simplicity.
+ */
+export class TeamsMessenger {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async sendNotification(input) {
+        const icon = this.severityIcon(input.severity);
+        const card = this.buildCard(`${icon} ${input.message}`);
+        await this.postWebhook(card);
+    }
+    async createThread(input) {
+        const card = this.buildCard(input.message, input.title);
+        await this.postWebhook(card);
+        // Teams webhooks don't return thread IDs, so generate a correlation ID
+        const threadId = `teams-${Date.now()}`;
+        return {
+            id: threadId,
+            url: this.config.webhookUrl,
+        };
+    }
+    async postUpdate(threadId, message) {
+        // Teams webhooks are fire-and-forget — no thread reply support
+        // Send as a new message referencing the thread
+        const card = this.buildCard(`[Thread: ${threadId}] ${message}`);
+        await this.postWebhook(card);
+    }
+    buildCard(message, title) {
+        const body = [];
+        if (title) {
+            body.push({
+                type: 'TextBlock',
+                text: title,
+                weight: 'Bolder',
+                size: 'Medium',
+                wrap: true,
+            });
+        }
+        body.push({
+            type: 'TextBlock',
+            text: message,
+            wrap: true,
+        });
+        return {
+            type: 'message',
+            attachments: [
+                {
+                    contentType: 'application/vnd.microsoft.card.adaptive',
+                    content: {
+                        $schema: 'http://adaptivecards.io/schemas/adaptive-card.json',
+                        type: 'AdaptiveCard',
+                        version: '1.4',
+                        body,
+                    },
+                },
+            ],
+        };
+    }
+    async postWebhook(card) {
+        const res = await fetch(this.config.webhookUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(card),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            throw new Error(`Teams webhook error ${res.status}: ${text.slice(0, 200)}`);
+        }
+    }
+    severityIcon(severity) {
+        switch (severity) {
+            case 'error':
+                return '🔴';
+            case 'warning':
+                return '⚠️';
+            default:
+                return 'ℹ️';
+        }
+    }
+}
+//# sourceMappingURL=teams-messenger.js.map

package/dist/notifications.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Notification template rendering utility.
+ * Replaces {key} placeholders in title and body with provided variable values.
+ */
+import type { NotificationTemplate } from '@ai-sdlc/reference';
+/**
+ * Render a notification template by replacing {key} placeholders with values.
+ */
+export declare function renderTemplate(template: NotificationTemplate, vars: Record<string, string>): {
+    title: string;
+    body: string;
+};
+//# sourceMappingURL=notifications.d.ts.map

package/dist/notifications.js

@@ -0,0 +1,15 @@
+/**
+ * Notification template rendering utility.
+ * Replaces {key} placeholders in title and body with provided variable values.
+ */
+import { interpolate } from './shared.js';
+/**
+ * Render a notification template by replacing {key} placeholders with values.
+ */
+export function renderTemplate(template, vars) {
+    return {
+        title: interpolate(template.title, vars),
+        body: interpolate(template.body ?? '', vars),
+    };
+}
+//# sourceMappingURL=notifications.js.map

package/dist/orchestration.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Agent orchestration integration — wraps multi-agent orchestration patterns,
+ * execution engine, and handoff validation for pipeline stages.
+ */
+import { sequential, parallel, hybrid, hierarchical, swarm, router, collaborative, executeOrchestration, validateHandoff, validateHandoffContract, simpleSchemaValidate, type OrchestrationPattern, type OrchestrationPlan, type OrchestrationStep, type OrchestrationResult, type StepResult, type TaskFn, type ExecutionOptions, type AgentRole } from '@ai-sdlc/reference';
+/**
+ * Create an orchestration plan appropriate for the given agent count and pattern.
+ */
+export declare function createPipelineOrchestration(agents: AgentRole[], pattern?: OrchestrationPattern): OrchestrationPlan;
+/**
+ * Execute an orchestration plan with a task function for each agent.
+ */
+export declare function executePipelineOrchestration(plan: OrchestrationPlan, agents: AgentRole[], taskFn: TaskFn, options?: ExecutionOptions): Promise<OrchestrationResult>;
+/**
+ * Validate that all handoff targets in an agent's handoff declarations exist.
+ */
+export declare function validatePipelineHandoffs(agents: AgentRole[]): string[];
+export { sequential, parallel, hybrid, hierarchical, swarm, router, collaborative, executeOrchestration, validateHandoff, validateHandoffContract, simpleSchemaValidate, };
+export type { OrchestrationPattern, OrchestrationPlan, OrchestrationStep, OrchestrationResult, StepResult, TaskFn, ExecutionOptions, };
+//# sourceMappingURL=orchestration.d.ts.map

package/dist/orchestration.js

@@ -0,0 +1,53 @@
+/**
+ * Agent orchestration integration — wraps multi-agent orchestration patterns,
+ * execution engine, and handoff validation for pipeline stages.
+ */
+import { sequential, parallel, hybrid, hierarchical, swarm, router, collaborative, executeOrchestration, validateHandoff, validateHandoffContract, simpleSchemaValidate, } from '@ai-sdlc/reference';
+/**
+ * Create an orchestration plan appropriate for the given agent count and pattern.
+ */
+export function createPipelineOrchestration(agents, pattern = 'sequential') {
+    switch (pattern) {
+        case 'sequential':
+            return sequential(agents);
+        case 'parallel':
+            return parallel(agents);
+        case 'hybrid':
+            return hybrid(agents[0], agents.slice(1));
+        case 'hierarchical':
+            return hierarchical(agents[0], agents.slice(1));
+        case 'swarm':
+            return swarm(agents);
+        default:
+            return sequential(agents);
+    }
+}
+/**
+ * Execute an orchestration plan with a task function for each agent.
+ */
+export async function executePipelineOrchestration(plan, agents, taskFn, options) {
+    const agentMap = new Map();
+    for (const agent of agents) {
+        agentMap.set(agent.metadata.name, agent);
+    }
+    return executeOrchestration(plan, agentMap, taskFn, options);
+}
+/**
+ * Validate that all handoff targets in an agent's handoff declarations exist.
+ */
+export function validatePipelineHandoffs(agents) {
+    const errors = [];
+    const agentNames = new Set(agents.map((a) => a.metadata.name));
+    for (const agent of agents) {
+        if (!agent.spec.handoffs)
+            continue;
+        for (const handoff of agent.spec.handoffs) {
+            if (!agentNames.has(handoff.target)) {
+                errors.push(`Agent "${agent.metadata.name}" has handoff to unknown target "${handoff.target}"`);
+            }
+        }
+    }
+    return errors;
+}
+export { sequential, parallel, hybrid, hierarchical, swarm, router, collaborative, executeOrchestration, validateHandoff, validateHandoffContract, simpleSchemaValidate, };
+//# sourceMappingURL=orchestration.js.map

package/dist/orchestrator.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Orchestrator class — central entry point wrapping executePipeline,
+ * startWatch, executeFixCI, and the state store.
+ */
+import { type ExecuteOptions, type PipelineResult } from './execute.js';
+import { type WatchOptions, type WatchHandle } from './watch.js';
+import { type FixCIOptions } from './fix-ci.js';
+import { type AiSdlcConfig } from './config.js';
+import { StateStore } from './state/index.js';
+import { type Logger } from './logger.js';
+import type { SecurityContext } from './security.js';
+import type { AgentRunner } from './runners/types.js';
+import type { CodebaseProfile, CodebaseContext } from './analysis/types.js';
+import type { AutonomyLedgerEntry, RoutingDecision } from './state/types.js';
+import { AutonomyTracker } from './autonomy-tracker.js';
+import { CostTracker, type CostSummary, type BudgetStatus } from './cost-tracker.js';
+import type { OrchestratorPlugin } from './plugin.js';
+export interface WebhookConfig {
+    /** Port to listen on for webhooks. */
+    port: number;
+    /** Host to bind to (defaults to '0.0.0.0'). */
+    host?: string;
+    /** GitHub webhook secret. */
+    githubSecret?: string;
+    /** GitLab webhook secret token. */
+    gitlabSecretToken?: string;
+    /** Jira webhook secret. */
+    jiraSecret?: string;
+    /** Linear webhook signing secret. */
+    linearSigningSecret?: string;
+}
+export interface OrchestratorConfig {
+    /** Path to the .ai-sdlc config directory. */
+    configDir?: string;
+    /** Working directory (defaults to process.cwd()). */
+    workDir?: string;
+    /** Path to the SQLite state database. Omit to disable persistence. */
+    statePath?: string;
+    /** Security context for enterprise features. */
+    security?: SecurityContext;
+    /** Custom agent runner override. */
+    runner?: AgentRunner;
+    /** Custom logger. */
+    logger?: Logger;
+    /** Webhook server configuration. */
+    webhooks?: WebhookConfig;
+    /** Plugins to hook into the pipeline lifecycle. */
+    plugins?: OrchestratorPlugin[];
+}
+export interface StatusResult {
+    config: AiSdlcConfig;
+    recentRuns: Array<{
+        runId: string;
+        issueNumber?: number;
+        status: string;
+        startedAt?: string;
+    }>;
+}
+export interface HealthResult {
+    configValid: boolean;
+    stateStoreConnected: boolean;
+    errors: string[];
+}
+export declare class Orchestrator {
+    private config;
+    private _state?;
+    private log;
+    private _autonomyTracker?;
+    private _costTracker?;
+    private plugins;
+    private _pluginsInitialized;
+    constructor(config: OrchestratorConfig);
+    private _initPlugins;
+    /**
+     * Run the full pipeline for a single issue.
+     */
+    run(issueNumber: number, overrides?: Partial<ExecuteOptions>): Promise<PipelineResult>;
+    /**
+     * Start watch mode — continuous reconciliation loop.
+     */
+    start(options?: Partial<WatchOptions>): Promise<WatchHandle>;
+    /**
+     * Fix a failing CI run on an agent-created PR.
+     */
+    fixCI(prNumber: number, runId: number, overrides?: Partial<FixCIOptions>): Promise<void>;
+    /**
+     * Get pipeline status, optionally filtered by issue number.
+     */
+    status(issueNumber?: number): Promise<StatusResult>;
+    /**
+     * Health check — validates config, state store, and adapter connectivity.
+     */
+    health(): Promise<HealthResult>;
+    /**
+     * Analyze the codebase and return a CodebaseProfile.
+     * Caches the result in the state store if available.
+     */
+    analyze(options?: {
+        force?: boolean;
+    }): Promise<CodebaseProfile>;
+    /**
+     * Get agent roster with autonomy levels and performance.
+     */
+    agents(): Promise<AutonomyLedgerEntry[]>;
+    /**
+     * Get routing decision history.
+     */
+    routing(options?: {
+        limit?: number;
+    }): Promise<RoutingDecision[]>;
+    /**
+     * Get codebase complexity profile as CodebaseContext.
+     */
+    complexity(options?: {
+        analyze?: boolean;
+    }): Promise<{
+        profile: CodebaseProfile;
+        context: CodebaseContext;
+    }>;
+    /**
+     * Get cost summary and budget status.
+     */
+    cost(opts?: {
+        since?: string;
+        budget?: number;
+    }): Promise<{
+        summary: CostSummary;
+        budget: BudgetStatus;
+    }>;
+    /**
+     * Get dashboard data snapshot for TUI rendering.
+     */
+    dashboard(): Promise<{
+        runs: Array<{
+            runId: string;
+            status: string;
+            startedAt?: string;
+        }>;
+        agents: AutonomyLedgerEntry[];
+        costSummary: CostSummary;
+        budgetStatus: BudgetStatus;
+    }>;
+    /**
+     * Access the autonomy tracker.
+     */
+    get autonomyTracker(): AutonomyTracker | undefined;
+    /**
+     * Access the cost tracker.
+     */
+    get costTracker(): CostTracker | undefined;
+    /**
+     * Access the state store directly.
+     */
+    get state(): StateStore | undefined;
+    /**
+     * Clean up resources. Calls shutdown() on all plugins.
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=orchestrator.d.ts.map