antigravity-ai-kit 3.1.1 → 3.2.0

package/lib/loading-engine.js

@@ -2,7 +2,9 @@
  * Antigravity AI Kit — Loading Rules Engine
  *
  * Runtime implementation of loading-rules.json keyword matching
- * and context budget enforcement.
+ * and context budget enforcement. Includes enhanced planning
+ * resolution with mandatory cross-cutting concerns, implicit
+ * domain triggers, and protected budget items.
  *
  * @module lib/loading-engine
  * @author Emre Dursun
@@ -14,10 +16,22 @@
 const fs = require('fs');
 const path = require('path');
 
-const AGENT_DIR = '.agent';
-const ENGINE_DIR = 'engine';
+const { AGENT_DIR, ENGINE_DIR } = require('./constants');
 const LOADING_RULES_FILE = 'loading-rules.json';
 
+/** Default maximum agents per session */
+const DEFAULT_MAX_AGENTS = 4;
+/** Default maximum skills per session */
+const DEFAULT_MAX_SKILLS = 8;
+/** Default warning threshold percentage */
+const DEFAULT_WARNING_THRESHOLD_PERCENT = 80;
+
+/**
+ * @typedef {object} ProtectedItems
+ * @property {string[]} [agents] - Agents exempt from budget trimming
+ * @property {string[]} [skills] - Skills exempt from budget trimming
+ */
+
 /**
  * @typedef {object} LoadPlan
  * @property {string[]} agents - Agents to load
@@ -29,6 +43,7 @@ const LOADING_RULES_FILE = 'loading-rules.json';
  * @property {number} budgetUsage.skillsUsed - Number of skills selected
  * @property {number} budgetUsage.skillsMax - Maximum allowed
  * @property {string[]} matchedDomains - Which domains matched
+ * @property {string[]} [mandatoryRules] - Rule files that must be consulted (planning only)
  */
 
 /**
@@ -47,6 +62,55 @@ function loadRules(projectRoot) {
   return JSON.parse(fs.readFileSync(rulesPath, 'utf-8'));
 }
 
+/**
+ * Trims an array of items respecting a protected set.
+ * Protected items survive trimming; non-protected items are dropped from end.
+ *
+ * @param {string[]} items - Items to potentially trim
+ * @param {Set<string>} protectedSet - Items exempt from trimming
+ * @param {number} max - Maximum allowed count
+ * @returns {{ result: string[], trimmed: boolean, warnings: string[] }}
+ */
+function trimWithProtection(items, protectedSet, max, label) {
+  if (items.length <= max) {
+    return { result: items, trimmed: false, warnings: [] };
+  }
+
+  const protectedArr = items.filter((i) => protectedSet.has(i));
+  const nonProtected = items.filter((i) => !protectedSet.has(i));
+  const slotsForNonProtected = Math.max(0, max - protectedArr.length);
+  const result = [...protectedArr, ...nonProtected.slice(0, slotsForNonProtected)];
+
+  const warnings = [
+    `${label} budget exceeded: ${items.length}/${max} — trimmed to ${result.length}`,
+  ];
+
+  if (protectedArr.length > max) {
+    warnings.push(`Protected ${label.toLowerCase()} (${protectedArr.length}) exceed budget (${max}) — budget override in effect`);
+  }
+
+  return { result, trimmed: true, warnings };
+}
+
+/**
+ * Builds a pre-compiled word-boundary regex from an array of trigger strings.
+ * Combines all triggers into a single alternation pattern for efficient matching.
+ *
+ * @param {string[]} triggers - Trigger strings to compile
+ * @returns {RegExp | null} Compiled regex, or null if no triggers
+ */
+function buildImplicitTriggerRegex(triggers) {
+  if (!triggers || triggers.length === 0) {
+    return null;
+  }
+
+  const pattern = triggers
+    .map((t) => t.toLowerCase().replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+    .join('|');
+
+  return new RegExp(`\\b(?:${pattern})\\b`);
+}
+
 /**
  * Matches a task description against domain keywords.
  *
@@ -55,7 +119,22 @@ function loadRules(projectRoot) {
  * @returns {{ matchedDomains: string[], agents: string[], skills: string[] }}
  */
 function resolveForTask(taskDescription, projectRoot) {
+  if (typeof taskDescription !== 'string') {
+    return { matchedDomains: [], agents: [], skills: [] };
+  }
+
   const rules = loadRules(projectRoot);
+  return resolveForTaskWithRules(taskDescription, rules);
+}
+
+/**
+ * Internal: Matches a task description against domain keywords using pre-loaded rules.
+ *
+ * @param {string} taskDescription - Human-readable task text
+ * @param {object} rules - Pre-loaded rules object
+ * @returns {{ matchedDomains: string[], agents: string[], skills: string[] }}
+ */
+function resolveForTaskWithRules(taskDescription, rules) {
   const domainRules = rules.domainRules || [];
   const lowerTask = taskDescription.toLowerCase();
 
@@ -88,6 +167,83 @@ function resolveForTask(taskDescription, projectRoot) {
   };
 }
 
+/**
+ * Enhanced task resolution for planning workflows.
+ * Extends standard keyword matching with implicit trigger detection
+ * and mandatory planning resources from planningMandates config.
+ *
+ * @param {string} taskDescription - Human-readable task text
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {{ matchedDomains: string[], agents: string[], skills: string[], mandatoryRules: string[] }}
+ */
+function resolveForPlanning(taskDescription, projectRoot) {
+  if (typeof taskDescription !== 'string') {
+    return { matchedDomains: [], agents: [], skills: [], mandatoryRules: [] };
+  }
+
+  const rules = loadRules(projectRoot);
+  return resolveForPlanningWithRules(taskDescription, rules);
+}
+
+/**
+ * Internal: Enhanced planning resolution using pre-loaded rules.
+ *
+ * @param {string} taskDescription - Human-readable task text
+ * @param {object} rules - Pre-loaded rules object
+ * @returns {{ matchedDomains: string[], agents: string[], skills: string[], mandatoryRules: string[] }}
+ */
+function resolveForPlanningWithRules(taskDescription, rules) {
+  const domainRules = rules.domainRules || [];
+  const planningMandates = rules.planningMandates || {};
+  const lowerTask = taskDescription.toLowerCase();
+
+  /** @type {Set<string>} */
+  const agents = new Set();
+  /** @type {Set<string>} */
+  const skills = new Set();
+  /** @type {string[]} */
+  const matchedDomains = [];
+
+  // Step 1: Standard keyword matching + implicit trigger detection
+  for (const rule of domainRules) {
+    const hasKeywordMatch = (rule.keywords || []).some(
+      (keyword) => lowerTask.includes(keyword.toLowerCase())
+    );
+
+    // Pre-compile a single regex for all implicit triggers per domain rule
+    const triggerRegex = buildImplicitTriggerRegex(rule.implicitTriggers);
+    const hasImplicitMatch = triggerRegex !== null && triggerRegex.test(lowerTask);
+
+    if (hasKeywordMatch || hasImplicitMatch) {
+      matchedDomains.push(rule.domain);
+
+      for (const agent of (rule.loadAgents || [])) {
+        agents.add(agent);
+      }
+      for (const skill of (rule.loadSkills || [])) {
+        skills.add(skill);
+      }
+    }
+  }
+
+  // Step 2: Merge mandatory planning skills
+  for (const skill of (planningMandates.alwaysLoadSkills || [])) {
+    skills.add(skill);
+  }
+
+  // Step 3: Build mandatory rules list (file paths for planner to reference)
+  const mandatoryRules = (planningMandates.alwaysLoadRules || []).map(
+    (ruleName) => path.join(AGENT_DIR, 'rules', `${ruleName}.md`)
+  );
+
+  return {
+    matchedDomains,
+    agents: [...agents],
+    skills: [...skills],
+    mandatoryRules,
+  };
+}
+
 /**
  * Resolves agents and skills for a named workflow using workflow bindings.
  *
@@ -97,6 +253,17 @@ function resolveForTask(taskDescription, projectRoot) {
  */
 function resolveForWorkflow(workflowName, projectRoot) {
   const rules = loadRules(projectRoot);
+  return resolveForWorkflowWithRules(workflowName, rules);
+}
+
+/**
+ * Internal: Resolves workflow bindings using pre-loaded rules.
+ *
+ * @param {string} workflowName - Name of the workflow
+ * @param {object} rules - Pre-loaded rules object
+ * @returns {{ agents: string[], skills: string[], bindingType: string }}
+ */
+function resolveForWorkflowWithRules(workflowName, rules) {
   const bindings = rules.workflowBindings || [];
   const match = bindings.find((b) => b.workflow === workflowName);
 
@@ -113,47 +280,62 @@ function resolveForWorkflow(workflowName, projectRoot) {
 
 /**
  * Enforces context budget limits by trimming agents and skills.
+ * Protected items (from planning mandates) are exempt from trimming.
  *
  * @param {string[]} agents - Candidate agents
  * @param {string[]} skills - Candidate skills
  * @param {string} projectRoot - Root directory of the project
+ * @param {ProtectedItems} [protectedItems] - Items exempt from budget trimming
  * @returns {{ agents: string[], skills: string[], trimmed: boolean, warnings: string[] }}
  */
-function enforceContextBudget(agents, skills, projectRoot) {
+function enforceContextBudget(agents, skills, projectRoot, protectedItems) {
   const rules = loadRules(projectRoot);
+  return enforceContextBudgetWithRules(agents, skills, rules, protectedItems);
+}
+
+/**
+ * Internal: Enforces context budget using pre-loaded rules.
+ *
+ * @param {string[]} agents - Candidate agents
+ * @param {string[]} skills - Candidate skills
+ * @param {object} rules - Pre-loaded rules object
+ * @param {ProtectedItems} [protectedItems] - Items exempt from budget trimming
+ * @returns {{ agents: string[], skills: string[], trimmed: boolean, warnings: string[] }}
+ */
+function enforceContextBudgetWithRules(agents, skills, rules, protectedItems) {
   const budget = rules.contextBudget || {};
-  const maxAgents = budget.maxAgentsPerSession || 4;
-  const maxSkills = budget.maxSkillsPerSession || 6;
-  const warningThreshold = (budget.warningThresholdPercent || 80) / 100;
+  const maxAgents = budget.maxAgentsPerSession || DEFAULT_MAX_AGENTS;
+  const maxSkills = budget.maxSkillsPerSession || DEFAULT_MAX_SKILLS;
+  const warningThreshold = (budget.warningThresholdPercent || DEFAULT_WARNING_THRESHOLD_PERCENT) / 100;
 
-  /** @type {string[]} */
-  const warnings = [];
-  let trimmed = false;
-
-  let finalAgents = [...agents];
-  let finalSkills = [...skills];
-
-  if (finalAgents.length > maxAgents) {
-    warnings.push(`Agent budget exceeded: ${finalAgents.length}/${maxAgents} — trimmed to ${maxAgents}`);
-    finalAgents = finalAgents.slice(0, maxAgents);
-    trimmed = true;
-  } else if (finalAgents.length >= maxAgents * warningThreshold) {
-    warnings.push(`Agent budget near limit: ${finalAgents.length}/${maxAgents} (${Math.round(finalAgents.length / maxAgents * 100)}%)`);
-  }
+  const protectedAgentSet = new Set((protectedItems && protectedItems.agents) || []);
+  const protectedSkillSet = new Set((protectedItems && protectedItems.skills) || []);
+
+  const agentTrim = trimWithProtection([...agents], protectedAgentSet, maxAgents, 'Agent');
+  const skillTrim = trimWithProtection([...skills], protectedSkillSet, maxSkills, 'Skill');
+
+  const warnings = [...agentTrim.warnings, ...skillTrim.warnings];
 
-  if (finalSkills.length > maxSkills) {
-    warnings.push(`Skill budget exceeded: ${finalSkills.length}/${maxSkills} — trimmed to ${maxSkills}`);
-    finalSkills = finalSkills.slice(0, maxSkills);
-    trimmed = true;
-  } else if (finalSkills.length >= maxSkills * warningThreshold) {
-    warnings.push(`Skill budget near limit: ${finalSkills.length}/${maxSkills} (${Math.round(finalSkills.length / maxSkills * 100)}%)`);
+  // Add near-limit warnings for non-trimmed cases
+  if (!agentTrim.trimmed && agentTrim.result.length >= maxAgents * warningThreshold) {
+    warnings.push(`Agent budget near limit: ${agentTrim.result.length}/${maxAgents} (${Math.round(agentTrim.result.length / maxAgents * 100)}%)`);
+  }
+  if (!skillTrim.trimmed && skillTrim.result.length >= maxSkills * warningThreshold) {
+    warnings.push(`Skill budget near limit: ${skillTrim.result.length}/${maxSkills} (${Math.round(skillTrim.result.length / maxSkills * 100)}%)`);
   }
 
-  return { agents: finalAgents, skills: finalSkills, trimmed, warnings };
+  return {
+    agents: agentTrim.result,
+    skills: skillTrim.result,
+    trimmed: agentTrim.trimmed || skillTrim.trimmed,
+    warnings,
+  };
 }
 
 /**
  * Full resolution: combines domain matching, workflow binding, and budget enforcement.
+ * Uses enhanced planning resolution when workflow is 'plan'.
+ * Loads rules once and passes through to all internal functions.
  *
  * @param {string} taskDescription - Task text for domain matching
  * @param {string} [workflowName] - Optional workflow name for binding resolution
@@ -161,11 +343,28 @@ function enforceContextBudget(agents, skills, projectRoot) {
  * @returns {LoadPlan}
  */
 function getLoadPlan(taskDescription, workflowName, projectRoot) {
+  if (typeof taskDescription !== 'string') {
+    return {
+      agents: [],
+      skills: [],
+      warnings: ['Invalid task description'],
+      budgetUsage: { agentsUsed: 0, agentsMax: DEFAULT_MAX_AGENTS, skillsUsed: 0, skillsMax: DEFAULT_MAX_SKILLS },
+      matchedDomains: [],
+    };
+  }
+
+  // Load rules ONCE and pass through to all helpers (H-1 fix)
   const rules = loadRules(projectRoot);
   const budget = rules.contextBudget || {};
+  const planningMandates = rules.planningMandates || {};
+  const isPlanWorkflow = workflowName === 'plan';
+  const maxAgents = budget.maxAgentsPerSession || DEFAULT_MAX_AGENTS;
+  const maxSkills = budget.maxSkillsPerSession || DEFAULT_MAX_SKILLS;
 
-  // Step 1: Domain keyword matching
-  const taskResolution = resolveForTask(taskDescription, projectRoot);
+  // Step 1: Domain matching (enhanced for planning workflows)
+  const taskResolution = isPlanWorkflow
+    ? resolveForPlanningWithRules(taskDescription, rules)
+    : resolveForTaskWithRules(taskDescription, rules);
 
   // Step 2: Workflow bindings (if workflow specified)
   /** @type {Set<string>} */
@@ -174,7 +373,7 @@ function getLoadPlan(taskDescription, workflowName, projectRoot) {
   const allSkills = new Set(taskResolution.skills);
 
   if (workflowName) {
-    const wfResolution = resolveForWorkflow(workflowName, projectRoot);
+    const wfResolution = resolveForWorkflowWithRules(workflowName, rules);
     for (const agent of wfResolution.agents) {
       allAgents.add(agent);
     }
@@ -183,25 +382,39 @@ function getLoadPlan(taskDescription, workflowName, projectRoot) {
     }
   }
 
-  // Step 3: Budget enforcement
-  const budgetResult = enforceContextBudget([...allAgents], [...allSkills], projectRoot);
+  // Step 3: Budget enforcement (with protected items for planning)
+  const protectedItems = isPlanWorkflow
+    ? { agents: [], skills: planningMandates.alwaysLoadSkills || [] }
+    : undefined;
+
+  const budgetResult = enforceContextBudgetWithRules(
+    [...allAgents],
+    [...allSkills],
+    rules,
+    protectedItems
+  );
 
+  // Construct complete object in one expression (H-3 immutability fix)
   return {
     agents: budgetResult.agents,
     skills: budgetResult.skills,
     warnings: budgetResult.warnings,
     budgetUsage: {
       agentsUsed: budgetResult.agents.length,
-      agentsMax: budget.maxAgentsPerSession || 4,
+      agentsMax: maxAgents,
       skillsUsed: budgetResult.skills.length,
-      skillsMax: budget.maxSkillsPerSession || 6,
+      skillsMax: maxSkills,
     },
     matchedDomains: taskResolution.matchedDomains,
+    ...(isPlanWorkflow && taskResolution.mandatoryRules
+      ? { mandatoryRules: taskResolution.mandatoryRules }
+      : {}),
   };
 }
 
 module.exports = {
   resolveForTask,
+  resolveForPlanning,
   resolveForWorkflow,
   enforceContextBudget,
   getLoadPlan,

package/lib/logger.js

@@ -0,0 +1,118 @@
+/**
+ * Antigravity AI Kit — Structured Logger
+ *
+ * Provides structured JSON logging with log levels, correlation IDs,
+ * and module context. Replaces raw console.log across all runtime modules.
+ *
+ * @module lib/logger
+ * @author Emre Dursun
+ * @since v3.2.0
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+
+/** @typedef {'debug' | 'info' | 'warn' | 'error'} LogLevel */
+
+const LOG_LEVELS = { debug: 0, info: 1, warn: 2, error: 3 };
+
+/** Default minimum log level */
+let minLevel = LOG_LEVELS[process.env.AG_LOG_LEVEL] ?? LOG_LEVELS.info;
+
+/** Output mode: 'json' for structured, 'text' for human-readable */
+let outputMode = process.env.AG_LOG_FORMAT === 'json' ? 'json' : 'text';
+
+/**
+ * Configures the logger.
+ *
+ * @param {object} options - Logger configuration
+ * @param {LogLevel} [options.level] - Minimum log level
+ * @param {'json' | 'text'} [options.format] - Output format
+ * @returns {void}
+ */
+function configure(options = {}) {
+  if (options.level && LOG_LEVELS[options.level] !== undefined) {
+    minLevel = LOG_LEVELS[options.level];
+  }
+  if (options.format === 'json' || options.format === 'text') {
+    outputMode = options.format;
+  }
+}
+
+/**
+ * Generates a short correlation ID for request tracing.
+ *
+ * @returns {string} 8-character hex correlation ID
+ */
+function correlationId() {
+  return crypto.randomBytes(4).toString('hex');
+}
+
+/**
+ * Creates a child logger scoped to a specific module.
+ *
+ * @param {string} moduleName - Module name for context
+ * @param {string} [corrId] - Optional correlation ID (auto-generated if omitted)
+ * @returns {{ debug: Function, info: Function, warn: Function, error: Function, child: Function }}
+ */
+function createLogger(moduleName, corrId) {
+  const cid = corrId || correlationId();
+
+  /**
+   * Emits a structured log entry.
+   *
+   * @param {LogLevel} level - Log level
+   * @param {string} message - Log message
+   * @param {object} [data] - Additional structured data
+   * @returns {void}
+   */
+  function emit(level, message, data) {
+    if (LOG_LEVELS[level] < minLevel) {
+      return;
+    }
+
+    const entry = {
+      timestamp: new Date().toISOString(),
+      level,
+      module: moduleName,
+      correlationId: cid,
+      message,
+      ...(data && Object.keys(data).length > 0 ? { data } : {}),
+    };
+
+    if (outputMode === 'json') {
+      const stream = level === 'error' ? process.stderr : process.stdout;
+      stream.write(JSON.stringify(entry) + '\n');
+    } else {
+      const prefix = `[${entry.timestamp.slice(11, 19)}] [${level.toUpperCase().padEnd(5)}] [${moduleName}]`;
+      const suffix = data && Object.keys(data).length > 0
+        ? ` ${JSON.stringify(data)}`
+        : '';
+      const stream = level === 'error' ? console.error : console.log;
+      stream(`${prefix} ${message}${suffix}`);
+    }
+  }
+
+  return {
+    debug: (message, data) => emit('debug', message, data),
+    info: (message, data) => emit('info', message, data),
+    warn: (message, data) => emit('warn', message, data),
+    error: (message, data) => emit('error', message, data),
+
+    /**
+     * Creates a child logger inheriting the correlation ID.
+     *
+     * @param {string} childModule - Child module name
+     * @returns {ReturnType<typeof createLogger>}
+     */
+    child: (childModule) => createLogger(childModule, cid),
+  };
+}
+
+module.exports = {
+  createLogger,
+  correlationId,
+  configure,
+  LOG_LEVELS,
+};

package/lib/marketplace.js

@@ -13,10 +13,14 @@
 
 const fs = require('fs');
 const path = require('path');
-const { execSync } = require('child_process');
-
-const AGENT_DIR = '.agent';
-const ENGINE_DIR = 'engine';
+const { execFileSync } = require('child_process');
+const { createCircuitBreaker } = require('./circuit-breaker');
+const { createRateLimiter } = require('./rate-limiter');
+
+const { AGENT_DIR, ENGINE_DIR } = require('./constants');
+const { writeJsonAtomic } = require('./io');
+const { createLogger } = require('./logger');
+const log = createLogger('marketplace');
 const INDEX_FILE = 'marketplace-index.json';
 
 /** Registry index TTL in milliseconds (24 hours) */
@@ -25,6 +29,18 @@ const INDEX_TTL_MS = 24 * 60 * 60 * 1000;
 /** Git clone timeout in milliseconds */
 const GIT_CLONE_TIMEOUT_MS = 30000;
 
+/** Circuit breaker for git clone operations */
+const gitCloneBreaker = createCircuitBreaker('marketplace-git-clone', {
+  failureThreshold: 3,
+  resetTimeoutMs: 120000,
+});
+
+/** Rate limiter for marketplace install operations (5 per minute) */
+const installLimiter = createRateLimiter('marketplace-install', {
+  maxTokens: 5,
+  refillRateMs: 60000,
+});
+
 /**
  * @typedef {object} MarketEntry
  * @property {string} name - Plugin name
@@ -74,15 +90,7 @@ function loadIndex(projectRoot) {
  */
 function writeIndex(projectRoot, data) {
   const filePath = resolveIndexPath(projectRoot);
-  const dir = path.dirname(filePath);
-
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
-  }
-
-  const tempPath = `${filePath}.tmp`;
-  fs.writeFileSync(tempPath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
-  fs.renameSync(tempPath, filePath);
+  writeJsonAtomic(filePath, data);
 }
 
 /**
@@ -209,18 +217,30 @@ function installFromMarket(projectRoot, pluginName) {
     return { success: false, message: `Invalid repository URL: ${entry.repository}` };
   }
 
+  // Rate limit check
+  const rateCheck = installLimiter.tryAcquire();
+  if (!rateCheck.allowed) {
+    return {
+      success: false,
+      message: `Rate limit exceeded — retry after ${Math.ceil(rateCheck.retryAfterMs / 1000)}s`,
+    };
+  }
+
   // Create temp directory for clone
   const tempDir = path.join(projectRoot, AGENT_DIR, ENGINE_DIR, `_temp_${Date.now()}`);
 
   try {
     fs.mkdirSync(tempDir, { recursive: true });
 
-    // Shallow clone with timeout (A-4)
+    // Shallow clone with circuit breaker and timeout (uses execFileSync to prevent shell injection)
     try {
-      execSync(
-        `git clone --depth 1 --single-branch "${entry.repository}" "${tempDir}"`,
-        { timeout: GIT_CLONE_TIMEOUT_MS, stdio: 'pipe' }
-      );
+      gitCloneBreaker.execute(() => {
+        execFileSync(
+          'git',
+          ['clone', '--depth', '1', '--single-branch', entry.repository, tempDir],
+          { timeout: GIT_CLONE_TIMEOUT_MS, stdio: 'pipe' }
+        );
+      });
     } catch (gitError) {
       return { success: false, message: `Git clone failed: ${gitError.message || 'timeout or network error'}` };
     }
@@ -250,8 +270,11 @@ function installFromMarket(projectRoot, pluginName) {
     // Delegate to plugin system for actual installation
     try {
       const pluginSystem = require('./plugin-system');
-      const result = pluginSystem.installPlugin(projectRoot, tempDir);
-      return { success: result.success, message: result.message || 'Plugin installed successfully' };
+      const result = pluginSystem.installPlugin(tempDir, projectRoot);
+      const message = result.errors?.length > 0
+        ? result.errors.join('; ')
+        : 'Plugin installed successfully';
+      return { success: result.success, message };
     } catch (installError) {
       return { success: false, message: `Plugin installation failed: ${installError.message}` };
     }