multi-agents-custom 2.0.0 → 2.1.0

package/dist/cli/index.mjs

@@ -1,83 +1,170 @@
 #!/usr/bin/env node
 import {
-  ConfigGenerator
-} from "../chunk-C62CM2KR.mjs";
+  ConfigGenerator,
+  MasterAgent
+} from "../chunk-PDPF4T5Z.mjs";
 
 // src/cli/index.ts
-var VALID_TARGETS = ["cursor", "copilot", "qwen", "antigravity", "all"];
-function parseArgs(argv) {
-  const config = {
-    targets: "all",
-    projectRoot: process.cwd(),
-    overwrite: false,
-    verbose: true,
-    help: false
-  };
-  for (const arg of argv) {
-    if (arg === "--help" || arg === "-h") {
-      config.help = true;
-    } else if (arg === "--overwrite") {
-      config.overwrite = true;
-    } else if (arg === "--quiet" || arg === "-q") {
-      config.verbose = false;
-    } else if (arg.startsWith("--targets=")) {
-      const raw = arg.slice("--targets=".length).split(",").map((s) => s.trim());
-      const valid = raw.filter((t) => VALID_TARGETS.includes(t));
-      if (valid.length !== raw.length) {
-        const invalid = raw.filter((t) => !VALID_TARGETS.includes(t));
-        console.error(`Unknown target(s): ${invalid.join(", ")}. Valid: ${VALID_TARGETS.join(", ")}`);
-        process.exit(1);
-      }
-      config.targets = valid.length === 1 ? valid[0] : valid;
-    } else if (arg.startsWith("--root=")) {
-      config.projectRoot = arg.slice("--root=".length);
-    }
-  }
-  return config;
+import * as readline from "readline";
+var VALID_TARGETS = ["cursor", "copilot", "qwen", "antigravity"];
+function createReadlineInterface() {
+  return readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
 }
-function printHelp() {
+function printBanner() {
   console.log(`
-Usage: npx multi-agents-custom [options]
-
-Generates AI tool config files for the multi-agent development pipeline into:
-  .cursor/rules/          \u2014 Cursor rules (*.mdc)
-  .github/prompts/        \u2014 GitHub Copilot prompt files (*.prompt.md)
-  .qwen/                  \u2014 Qwen instruction files (*.md)
-  .antigravity/           \u2014 Antigravity persona files (*.md)
-
-Options:
-  --targets=<list>    Comma-separated list of tools to target.
-                      Valid: cursor, copilot, qwen, antigravity, all
-                      Default: all
-  --root=<path>       Project root directory. Default: current working directory
-  --overwrite         Overwrite existing config files (default: skip existing)
-  --quiet, -q         Suppress progress output
-  --help, -h          Show this help message
-`);
+\u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557
+\u2551     Multi-Agents Custom - AI Tool Config Generator       \u2551
+\u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255D
+  `);
 }
-async function main() {
-  if (process.env.SKIP_MULTI_AGENTS_POSTINSTALL === "1") {
-    return;
+async function askQuestion(rl, question) {
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      resolve(answer.trim());
+    });
+  });
+}
+async function askYesNo(rl, question, defaultValue = true) {
+  const defaultStr = defaultValue ? "Y/n" : "y/N";
+  const answer = await askQuestion(rl, `${question} (${defaultStr}): `);
+  if (answer === "") {
+    return defaultValue;
   }
-  const installRoot = process.env.INIT_CWD ?? process.cwd();
-  const args = process.argv.slice(2);
-  const config = parseArgs(args);
-  if (config.help) {
-    printHelp();
-    return;
+  return ["y", "yes", "Y"].includes(answer.toLowerCase());
+}
+async function selectLanguage(rl) {
+  console.log("\n\u{1F310} Step 1: Select Output Language");
+  console.log("   Choose the language for generated agent config file content:\n");
+  console.log("   1) en \u2014 English (default)");
+  console.log("   2) vi \u2014 Ti\u1EBFng Vi\u1EC7t");
+  const answer = await askQuestion(rl, "\n   Enter choice [1]: ");
+  return answer.trim() === "2" || answer.trim().toLowerCase() === "vi" ? "vi" : "en";
+}
+async function selectTargets(rl) {
+  console.log("\n\u{1F4E6} Step 2: Select AI Tools to Configure");
+  console.log("   Choose which AI tools you want to generate config files for:\n");
+  const targets = [];
+  const descriptions = {
+    cursor: "Cursor IDE (.cursor/rules/*.mdc)",
+    copilot: "GitHub Copilot (.github/prompts/*.prompt.md)",
+    qwen: "Qwen Code (.qwen/*.md)",
+    antigravity: "AntiGravity (.antigravity/*.md)"
+  };
+  for (const target of VALID_TARGETS) {
+    const selected = await askYesNo(rl, `   ${target} - ${descriptions[target]}`, true);
+    if (selected) {
+      targets.push(target);
+    }
+  }
+  if (targets.length === 0) {
+    console.log("\n\u26A0\uFE0F  No tools selected. Defaulting to all tools.");
+    return "all";
   }
-  if (!args.some((a) => a.startsWith("--root="))) {
-    config.projectRoot = installRoot;
+  if (targets.length === VALID_TARGETS.length) {
+    console.log("\n\u2713 All tools selected.");
+    return "all";
   }
-  const generator = new ConfigGenerator(config);
+  return targets;
+}
+async function getProjectRoot(rl, defaultRoot) {
+  console.log("\n\u{1F4C1} Step 3: Project Root Directory");
+  const answer = await askQuestion(rl, `   Enter project root path [${defaultRoot}]: `);
+  return answer || defaultRoot;
+}
+async function askOverwrite(rl) {
+  console.log("\n\u26A0\uFE0F  Step 4: Overwrite Existing Files");
+  return await askYesNo(rl, "   Overwrite existing config files if they exist?", false);
+}
+async function askMasterAgent(rl) {
+  console.log("\n\u{1F916} Step 5: Master Agent Orchestration");
+  const useMaster = await askYesNo(rl, "   Run the Master Agent to orchestrate the pipeline?", false);
+  if (useMaster) {
+    const prompt = await askQuestion(rl, "   Enter your feature description: ");
+    return { master: true, prompt: prompt || void 0 };
+  }
+  return { master: false };
+}
+async function runInteractiveSetup() {
+  const rl = createReadlineInterface();
   try {
+    printBanner();
+    console.log("\u{1F44B} Welcome! This wizard will help you set up AI tool configurations.");
+    console.log("   Press Ctrl+C at any time to cancel.\n");
+    const installRoot = process.env.INIT_CWD ?? process.cwd();
+    const language = await selectLanguage(rl);
+    const targets = await selectTargets(rl);
+    const projectRoot = await getProjectRoot(rl, installRoot);
+    const overwrite = await askOverwrite(rl);
+    const { master, prompt } = await askMasterAgent(rl);
+    console.log("\n\u{1F4CB} Configuration Summary:");
+    console.log(`   Language: ${language === "vi" ? "\u{1F1FB}\u{1F1F3} Ti\u1EBFng Vi\u1EC7t" : "\u{1F1EC}\u{1F1E7} English"}`);
+    console.log(`   Targets: ${targets === "all" ? "All tools" : targets.join(", ")}`);
+    console.log(`   Project Root: ${projectRoot}`);
+    console.log(`   Overwrite Existing: ${overwrite ? "Yes" : "No"}`);
+    console.log(`   Master Agent: ${master ? "Yes" : "No"}${prompt ? ` - "${prompt}"` : ""}`);
+    const confirm = await askYesNo(rl, "\n\u2705 Proceed with this configuration?", true);
+    if (!confirm) {
+      console.log("\n\u274C Installation cancelled.");
+      rl.close();
+      return;
+    }
+    rl.close();
+    const config = {
+      targets,
+      projectRoot,
+      language,
+      overwrite,
+      verbose: true,
+      master,
+      prompt
+    };
+    if (master && prompt) {
+      const masterAgent = MasterAgent.getInstance();
+      console.log(`
+\x1B[35m[MasterAgent]\x1B[0m Orchestrating: "${prompt}"
+`);
+      for await (const event of masterAgent.run(prompt)) {
+        const icon = event.type === "success" ? "\u2705" : event.type === "error" ? "\u274C" : "\u2139\uFE0F";
+        process.stdout.write(`${icon} [${event.agentId}] ${event.message}
+`);
+      }
+      return;
+    }
+    const generator = new ConfigGenerator(config);
     const result = await generator.generate();
-    if (!result.success) {
+    if (result.success) {
+      console.log("\n\u2705 Configuration generated successfully!");
+    } else {
+      console.log("\n\u274C Failed to generate configuration.");
       process.exit(1);
     }
   } catch (err) {
-    console.error("multi-agents-custom: unexpected error during config generation:", err);
+    rl.close();
+    console.error("\n\u274C Error during setup:", err);
     process.exit(1);
   }
 }
+async function main() {
+  if (process.env.SKIP_MULTI_AGENTS_POSTINSTALL === "1") {
+    return;
+  }
+  const isCI = process.env.CI === "true" || !process.stdin.isTTY;
+  if (isCI) {
+    const installRoot = process.env.INIT_CWD ?? process.cwd();
+    const config = {
+      targets: "all",
+      projectRoot: installRoot,
+      overwrite: false,
+      verbose: true,
+      master: false
+    };
+    const generator = new ConfigGenerator(config);
+    await generator.generate();
+    return;
+  }
+  await runInteractiveSetup();
+}
 main();

package/dist/index.d.mts

@@ -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 };