multi-agents-custom 2.0.0 → 2.1.0

package/dist/index.d.ts

@@ -1,11 +1,77 @@
+import { EventEmitter } from 'events';
+
 /**
  * Supported AI tool targets that can receive generated config files.
  */
 type ToolTarget = 'cursor' | 'copilot' | 'qwen' | 'antigravity' | 'all';
 /**
- * The five agent roles in the software development pipeline.
+ * Supported output languages for generated config file content.
+ * @default 'en'
+ */
+type Language = 'en' | 'vi';
+/**
+ * The six agent roles in the software development pipeline.
  */
-type AgentRole = 'pm' | 'ba' | 'techlead' | 'developer' | 'tester';
+type AgentRole = 'pm' | 'ba' | 'techlead' | 'developer' | 'devlead' | 'tester';
+type ReviewSeverity = 'BLOCKER' | 'MAJOR' | 'MINOR';
+type ReviewCategory = 'DESIGN' | 'QUALITY' | 'OWASP';
+/** A single file included in a code-change diff */
+interface DiffFile {
+    /** Repo-relative path to the changed file */
+    filePath: string;
+    /** File content before the change (empty string for new files) */
+    before: string;
+    /** File content after the change */
+    after: string;
+}
+/** Set of changed files representing a developer's completed change-set */
+interface Diff {
+    /** Kebab-case feature identifier */
+    featureName: string;
+    /** Individual file changes */
+    files: DiffFile[];
+}
+/** Input context passed to the DevLeadAgent for a review cycle */
+interface ReviewContext {
+    /** Kebab-case feature identifier */
+    featureName: string;
+    /** Code diff to review */
+    diff: Diff;
+    /** Path to docs/ai/implementation/feature-{name}.md */
+    implementationDocPath: string;
+    /** Path to docs/ai/design/feature-{name}.md */
+    designDocPath: string;
+}
+/** A single inline review comment produced by a checker */
+interface Finding {
+    /** Source file or doc path where the issue was found */
+    file: string;
+    /** Line number (null for doc-level findings) */
+    line: number | null;
+    /** Impact on pipeline advancement */
+    severity: ReviewSeverity;
+    /** Which checker raised this finding */
+    category: ReviewCategory;
+    /** OWASP Top 10 category label (only set when category === 'OWASP') */
+    owaspCategory: string | null;
+    /** Human-readable description of the issue */
+    message: string;
+    /** Optional remediation suggestion */
+    suggestion: string | null;
+}
+/** Aggregated output of a full Dev Lead review cycle */
+interface ReviewReport {
+    /** Feature being reviewed */
+    featureName: string;
+    /** ISO-8601 review timestamp */
+    timestamp: string;
+    /** PASS = no BLOCKERs; CHANGES_REQUESTED = at least one BLOCKER */
+    outcome: 'PASS' | 'CHANGES_REQUESTED';
+    /** All inline comments from all checkers */
+    findings: Finding[];
+    /** Prose summary of the review */
+    summary: string;
+}
 /**
  * A single agent persona definition used to generate config files.
  */
@@ -40,6 +106,11 @@ interface GeneratorConfig {
      * Per-agent overrides for system prompts or metadata.
      */
     agents?: Partial<Record<AgentRole, Partial<AgentPersona>>>;
+    /**
+     * Language for generated config file content.
+     * @default 'en'
+     */
+    language?: Language;
     /**
      * Whether to overwrite existing config files.
      * @default false
@@ -138,9 +209,219 @@ declare class ConfigGenerator {
  */
 declare const DEFAULT_PERSONAS: AgentPersona[];
 /**
- * Returns all default personas, optionally merged with per-role overrides.
+ * Returns all default personas, optionally merged with per-role overrides
+ * and/or translated to the specified language.
+ *
+ * Language translation is applied first, then per-role overrides on top.
+ *
+ * @param overrides  Optional per-role overrides for system prompts or metadata.
+ * @param language   Output language for generated content. Defaults to 'en'.
+ */
+declare function buildPersonas(overrides?: Partial<Record<string, Partial<AgentPersona>>>, language?: Language): AgentPersona[];
+
+interface Message {
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+}
+declare enum AgentStatus {
+    IDLE = "IDLE",
+    PLANNING = "PLANNING",
+    EXECUTING = "EXECUTING",
+    REVIEWING = "REVIEWING"
+}
+interface AIContext {
+    sessionId: string;
+    history: Message[];
+    documents: Map<string, string>;
+    status: AgentStatus;
+}
+interface AgentProgressEvent {
+    agentId: string;
+    message: string;
+    type: 'info' | 'success' | 'warning' | 'error';
+}
+declare abstract class BaseAgent {
+    abstract id: string;
+    abstract run(context: AIContext): Promise<string>;
+}
+
+interface AgentExecutionResult {
+    agentId: string;
+    success: boolean;
+    output: string;
+    error?: string;
+}
+declare class MasterAgent extends EventEmitter {
+    private static instance;
+    private context;
+    private workflowQueue;
+    private executionResults;
+    private constructor();
+    static getInstance(): MasterAgent;
+    run(input: string): AsyncGenerator<AgentProgressEvent>;
+    private planWorkflow;
+    private executeAgent;
+    private buildAgentContext;
+    private simulateAgentExecution;
+    private generatePMOutput;
+    private generateBAOutput;
+    private generateTechLeadOutput;
+    private generateDeveloperOutput;
+    private generateDevLeadOutput;
+    private generateTesterOutput;
+    getContext(): AIContext;
+    getExecutionResults(): Map<AgentRole, AgentExecutionResult>;
+    reset(): void;
+}
+
+/**
+ * Design Adherence Checker.
+ *
+ * Compares the code diff and implementation doc against the approved design doc,
+ * flagging deviations from agreed components, data models, and API contracts.
  */
-declare function buildPersonas(overrides?: Partial<Record<string, Partial<AgentPersona>>>): AgentPersona[];
+declare class DesignChecker {
+    /**
+     * @param diff            Set of changed files.
+     * @param implDoc         Content of docs/ai/implementation/feature-{name}.md.
+     * @param designDoc       Content of docs/ai/design/feature-{name}.md.
+     */
+    check(diff: Diff, implDoc: string, designDoc: string): Finding[];
+    /**
+     * Extract bold component names from the design doc Components table.
+     * Matches `**ComponentName**` patterns.
+     */
+    extractComponents(designDoc: string): string[];
+    /**
+     * Extract interface/type names from the design doc API/Data-model sections.
+     * Matches `interface FooBar` or `type FooBar` patterns.
+     */
+    extractInterfaces(designDoc: string): string[];
+    private checkComponentPresence;
+    private checkInterfaceConformance;
+    private checkNoNewUnlistedExports;
+    private checkImplDocCoverage;
+}
+
+/**
+ * Code Quality Checker.
+ *
+ * Applies coding standards to the diff: naming conventions, function length,
+ * TypeScript strict-mode compliance, TODO comments, and unsafe patterns.
+ */
+declare class QualityChecker {
+    private static readonly MAX_FUNCTION_LINES;
+    /**
+     * @param diff  Set of changed files to analyse.
+     */
+    check(diff: Diff): Finding[];
+    private checkAnyUsage;
+    private checkFunctionLength;
+    private checkMissingReturnTypes;
+    private checkTodoComments;
+    private checkConsoleStatements;
+    private checkNonNullAssertions;
+}
+
+/**
+ * OWASP Security Checker.
+ *
+ * Scans modified TypeScript files for OWASP Top 10 security issues:
+ *   A01 — Broken Access Control
+ *   A02 — Cryptographic Failures
+ *   A03 — Injection (SQL, command, eval)
+ *   A05 — Security Misconfiguration
+ *   A07 — Identification and Authentication Failures
+ *   A10 — Server-Side Request Forgery (SSRF)
+ */
+declare class OWASPChecker {
+    /**
+     * @param diff  Set of changed files to analyse.
+     */
+    check(diff: Diff): Finding[];
+    private checkHardcodedSecrets;
+    private checkWeakCrypto;
+    private checkInjection;
+    private checkMissingAuthChecks;
+    private checkSSRF;
+    private checkInsecureConfigs;
+}
+
+/**
+ * Review Report Builder.
+ *
+ * Aggregates findings from all checkers into a structured ReviewReport.
+ * Outcome logic:
+ *   - CHANGES_REQUESTED if any finding has severity === 'BLOCKER'
+ *   - PASS otherwise (MAJOR/MINOR findings are surfaced but do not block)
+ */
+declare class ReportBuilder {
+    /**
+     * @param featureName  Kebab-case feature name.
+     * @param findings     All findings from all checkers.
+     */
+    build(featureName: string, findings: Finding[]): ReviewReport;
+    private buildSummary;
+}
+
+type ConfirmationResult = {
+    decision: 'approved';
+} | {
+    decision: 'rejected';
+    note: string;
+};
+/**
+ * Human Confirmation Gate.
+ *
+ * Prints the ReviewReport to stdout and blocks until the user inputs
+ * `/approve` or `/reject [optional note]`.
+ *
+ * Pipeline behaviour:
+ *   /approve  → report is passed to the Tester as read-only context
+ *   /reject   → report + optional note re-queued to Developer as context
+ */
+declare class ConfirmationGate {
+    /**
+     * Display the report and wait for human confirmation.
+     *
+     * @param report  The completed ReviewReport from the ReportBuilder.
+     * @returns       The human's decision plus any rejection note.
+     */
+    wait(report: ReviewReport): Promise<ConfirmationResult>;
+    private printReport;
+    private promptUser;
+}
+
+/**
+ * DevLeadAgent — Phase 4.5: Code Review Gate.
+ *
+ * Positioned between the Developer and Tester agents in the pipeline.
+ * Orchestrates three checkers (Design, Quality, OWASP), builds a structured
+ * ReviewReport, persists it to docs/ai/review/, then waits for human
+ * confirmation before allowing the pipeline to advance.
+ */
+declare class DevLeadAgent {
+    private readonly designChecker;
+    private readonly qualityChecker;
+    private readonly owaspChecker;
+    private readonly reportBuilder;
+    private readonly confirmationGate;
+    constructor(designChecker?: DesignChecker, qualityChecker?: QualityChecker, owaspChecker?: OWASPChecker, reportBuilder?: ReportBuilder, confirmationGate?: ConfirmationGate);
+    /**
+     * Run a full review cycle for a feature's code changes.
+     *
+     * 1. Loads the design doc and implementation doc from disk.
+     * 2. Runs all three checkers against the diff.
+     * 3. Builds and persists the ReviewReport.
+     * 4. Presents the report to the human and waits for /approve or /reject.
+     *
+     * @returns The completed ReviewReport (includes human decision in calling context).
+     * @throws  If required doc files cannot be read.
+     */
+    review(context: ReviewContext): Promise<ReviewReport>;
+    private readDoc;
+    private persistReport;
+}
 
 /**
  * Generates `.cursor/rules/<role>.mdc` files.
@@ -221,4 +502,4 @@ declare class Logger {
     heading(msg: string): void;
 }
 
-export { type AgentPersona, type AgentRole, AntigravityWriter, ConfigGenerator, CopilotWriter, CursorWriter, DEFAULT_PERSONAS, type GeneratorConfig, type GeneratorResult, type IProviderWriter, Logger, QwenWriter, type ToolTarget, type WriteResult, buildPersonas, resolveWriters };
+export { type AIContext, type AgentExecutionResult, type AgentPersona, type AgentProgressEvent, type AgentRole, AgentStatus, AntigravityWriter, BaseAgent, ConfigGenerator, CopilotWriter, CursorWriter, DEFAULT_PERSONAS, DevLeadAgent, type Diff, type DiffFile, type Finding, type GeneratorConfig, type GeneratorResult, type IProviderWriter, type Language, Logger, MasterAgent, type Message, QwenWriter, type ReviewCategory, type ReviewContext, type ReviewReport, type ReviewSeverity, type ToolTarget, type WriteResult, buildPersonas, resolveWriters };