@agentlee5/agent-skills 1.0.0

package/LeeWay-Standards/src/agents/mcp/endpoint-agent.js

@@ -0,0 +1,106 @@
+/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: MCP.AGENT.ENDPOINT
+TAG: MCP.ENDPOINT.AGENT.MAIN
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=globe
+
+5WH:
+WHAT = Endpoint agent — detects existing health and HTTP endpoints safely
+WHY = Prevents duplicate endpoint registration and detects port conflicts before startup
+WHO = Rapid Web Development
+WHERE = src/agents/mcp/endpoint-agent.js
+WHEN = 2026
+HOW = Reads manifest files and scans source for endpoint declarations
+
+AGENTS:
+ENDPOINT
+TRANSPORT
+PORT
+
+LICENSE:
+MIT
+*/
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+const ENDPOINT_PATTERNS = [
+  { type: 'express', pattern: /app\.(get|post|put|delete|patch|use)\s*\(\s*['"`]([^'"`]+)['"`]/g },
+  { type: 'fastify', pattern: /fastify\.(get|post|put|delete|patch)\s*\(\s*['"`]([^'"`]+)['"`]/g },
+  { type: 'http', pattern: /createServer|http\.listen\s*\(\s*(\d+)/g },
+];
+
+/**
+ * EndpointAgent detects existing HTTP endpoints and health checks in source files.
+ */
+export class EndpointAgent {
+  constructor(options = {}) {
+    this.rootDir = options.rootDir || process.cwd();
+    this.knownEndpoints = new Map();
+  }
+
+  /**
+   * Scan a file for endpoint declarations.
+   *
+   * @param {string} filePath
+   * @returns {Promise<EndpointScanResult>}
+   */
+  async scanFile(filePath) {
+    const fullPath = filePath.startsWith('/') ? filePath : join(this.rootDir, filePath);
+    let content = '';
+    try {
+      content = await readFile(fullPath, 'utf8');
+    } catch {
+      return { file: filePath, endpoints: [], status: 'error' };
+    }
+
+    const endpoints = [];
+    for (const { type, pattern } of ENDPOINT_PATTERNS) {
+      const regex = new RegExp(pattern.source, pattern.flags);
+      let match;
+      while ((match = regex.exec(content)) !== null) {
+        endpoints.push({
+          type,
+          method: match[1]?.toUpperCase() || 'UNKNOWN',
+          path: match[2] || '/',
+          line: content.slice(0, match.index).split('\n').length,
+        });
+      }
+    }
+
+    return { file: filePath, endpoints, status: 'scanned' };
+  }
+
+  /**
+   * Check for duplicate endpoints across multiple scan results.
+   *
+   * @param {EndpointScanResult[]} scanResults
+   * @returns {{ duplicates: object[], unique: object[] }}
+   */
+  detectDuplicates(scanResults) {
+    const seen = new Map();
+    const duplicates = [];
+
+    for (const result of scanResults) {
+      for (const ep of result.endpoints) {
+        const key = `${ep.method}:${ep.path}`;
+        if (seen.has(key)) {
+          duplicates.push({ key, files: [seen.get(key).file, result.file], endpoint: ep });
+        } else {
+          seen.set(key, { ...ep, file: result.file });
+        }
+      }
+    }
+
+    return { duplicates, unique: Array.from(seen.values()) };
+  }
+}

package/LeeWay-Standards/src/agents/mcp/env-agent.js

@@ -0,0 +1,111 @@
+/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: MCP.AGENT.ENV
+TAG: MCP.ENV.AGENT.MAIN
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=settings
+
+5WH:
+WHAT = Env agent — validates required vs optional environment variables
+WHY = Missing or misconfigured env vars cause runtime failures that are hard to debug
+WHO = Rapid Web Development
+WHERE = src/agents/mcp/env-agent.js
+WHEN = 2026
+HOW = Reads .leeway/env-schema.json and validates against process.env
+
+AGENTS:
+ENV
+RUNTIME
+ALIGN
+
+LICENSE:
+MIT
+*/
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * EnvAgent validates environment variable presence and format.
+ */
+export class EnvAgent {
+  constructor(options = {}) {
+    this.rootDir = options.rootDir || process.cwd();
+    this.schema = null;
+  }
+
+  /**
+   * Load the env schema from .leeway/env-schema.json or .env.schema.json
+   */
+  async loadSchema() {
+    const paths = [
+      join(this.rootDir, '.leeway', 'env-schema.json'),
+      join(this.rootDir, '.env.schema.json'),
+    ];
+
+    for (const p of paths) {
+      try {
+        const raw = await readFile(p, 'utf8');
+        this.schema = JSON.parse(raw);
+        return this.schema;
+      } catch {
+        continue;
+      }
+    }
+
+    this.schema = { required: [], optional: [] };
+    return this.schema;
+  }
+
+  /**
+   * Validate current environment against the schema.
+   *
+   * @param {object} [env] - Environment to validate (defaults to process.env)
+   * @returns {Promise<EnvValidationResult>}
+   */
+  async validate(env = process.env) {
+    if (!this.schema) await this.loadSchema();
+
+    const missing = [];
+    const present = [];
+    const warnings = [];
+
+    for (const varDef of this.schema.required || []) {
+      const name = typeof varDef === 'string' ? varDef : varDef.name;
+      const pattern = typeof varDef === 'object' ? varDef.pattern : null;
+
+      if (!env[name]) {
+        missing.push(name);
+      } else {
+        if (pattern && !new RegExp(pattern).test(env[name])) {
+          warnings.push(`${name} does not match expected pattern`);
+        }
+        present.push(name);
+      }
+    }
+
+    for (const varDef of this.schema.optional || []) {
+      const name = typeof varDef === 'string' ? varDef : varDef.name;
+      if (!env[name]) {
+        warnings.push(`Optional env var ${name} is not set`);
+      } else {
+        present.push(name);
+      }
+    }
+
+    return {
+      valid: missing.length === 0,
+      missing,
+      present,
+      warnings,
+    };
+  }
+}

package/LeeWay-Standards/src/agents/mcp/health-agent-lite.js

@@ -0,0 +1,119 @@
+/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: MCP.AGENT.HEALTH
+TAG: MCP.HEALTH.AGENT.LITE
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=heart-pulse
+
+5WH:
+WHAT = Health agent lite — runs lightweight startup and readiness checks
+WHY = Services must pass readiness gates before routing traffic or accepting requests
+WHO = Rapid Web Development
+WHERE = src/agents/mcp/health-agent-lite.js
+WHEN = 2026
+HOW = Runs a series of configurable health checks, returns pass/fail with details
+
+AGENTS:
+HEALTH
+RUNTIME
+ENV
+
+LICENSE:
+MIT
+*/
+
+/**
+ * HealthAgentLite performs lightweight startup and readiness checks.
+ */
+export class HealthAgentLite {
+  constructor(options = {}) {
+    this.checks = options.checks || [];
+    this.timeout = options.timeout || 5000;
+  }
+
+  /**
+   * Register a health check function.
+   *
+   * @param {string} name
+   * @param {() => Promise<{ healthy: boolean, details?: string }>} fn
+   */
+  register(name, fn) {
+    this.checks.push({ name, fn });
+  }
+
+  /**
+   * Run all registered health checks.
+   * @returns {Promise<HealthReport>}
+   */
+  async run() {
+    const results = [];
+    let allHealthy = true;
+
+    for (const check of this.checks) {
+      const startTime = Date.now();
+      try {
+        const result = await Promise.race([
+          check.fn(),
+          new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), this.timeout)),
+        ]);
+
+        const duration = Date.now() - startTime;
+        results.push({
+          name: check.name,
+          healthy: result.healthy,
+          details: result.details || null,
+          durationMs: duration,
+        });
+
+        if (!result.healthy) allHealthy = false;
+      } catch (err) {
+        results.push({
+          name: check.name,
+          healthy: false,
+          details: err.message,
+          durationMs: Date.now() - startTime,
+        });
+        allHealthy = false;
+      }
+    }
+
+    return {
+      healthy: allHealthy,
+      timestamp: new Date().toISOString(),
+      checks: results,
+      summary: `${results.filter(r => r.healthy).length}/${results.length} checks passed`,
+    };
+  }
+
+  /**
+   * Get built-in system health checks.
+   * @returns {HealthAgentLite}
+   */
+  static withSystemChecks(options = {}) {
+    const agent = new HealthAgentLite(options);
+
+    agent.register('memory', async () => {
+      const { heapUsed, heapTotal } = process.memoryUsage();
+      const usagePercent = Math.round((heapUsed / heapTotal) * 100);
+      return {
+        healthy: usagePercent < 90,
+        details: `Heap usage: ${usagePercent}% (${Math.round(heapUsed / 1024 / 1024)}MB / ${Math.round(heapTotal / 1024 / 1024)}MB)`,
+      };
+    });
+
+    agent.register('uptime', async () => ({
+      healthy: true,
+      details: `Process uptime: ${Math.round(process.uptime())}s`,
+    }));
+
+    return agent;
+  }
+}

package/LeeWay-Standards/src/agents/mcp/manifest-agent.js

@@ -0,0 +1,87 @@
+/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: MCP.AGENT.MANIFEST
+TAG: MCP.MANIFEST.AGENT.MAIN
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=file-check
+
+5WH:
+WHAT = Manifest agent — validates MCP manifest completeness and tool definitions
+WHY = Incomplete or malformed manifests prevent MCP servers from being discovered and used
+WHO = Rapid Web Development
+WHERE = src/agents/mcp/manifest-agent.js
+WHEN = 2026
+HOW = Reads manifest JSON, validates required fields and tool schemas
+
+AGENTS:
+MANIFEST
+TRANSPORT
+ENDPOINT
+
+LICENSE:
+MIT
+*/
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+const REQUIRED_MANIFEST_FIELDS = ['name', 'version', 'description'];
+const REQUIRED_TOOL_FIELDS = ['name', 'description', 'inputSchema'];
+
+/**
+ * ManifestAgent validates MCP manifest files for completeness.
+ */
+export class ManifestAgent {
+  constructor(options = {}) {
+    this.rootDir = options.rootDir || process.cwd();
+  }
+
+  /**
+   * Validate a manifest object or load from file.
+   *
+   * @param {string | object} manifestOrPath - Manifest object or path to manifest file
+   * @returns {Promise<ManifestValidationResult>}
+   */
+  async validate(manifestOrPath) {
+    let manifest = manifestOrPath;
+
+    if (typeof manifestOrPath === 'string') {
+      const fullPath = manifestOrPath.startsWith('/') ? manifestOrPath : join(this.rootDir, manifestOrPath);
+      try {
+        const raw = await readFile(fullPath, 'utf8');
+        manifest = JSON.parse(raw);
+      } catch (err) {
+        return { valid: false, issues: [`Cannot load manifest: ${err.message}`] };
+      }
+    }
+
+    const issues = [];
+
+    for (const field of REQUIRED_MANIFEST_FIELDS) {
+      if (!manifest[field]) issues.push(`Missing required field: ${field}`);
+    }
+
+    if (manifest.tools && Array.isArray(manifest.tools)) {
+      for (const tool of manifest.tools) {
+        for (const field of REQUIRED_TOOL_FIELDS) {
+          if (!tool[field]) issues.push(`Tool "${tool.name || 'unknown'}" missing field: ${field}`);
+        }
+        if (tool.inputSchema && typeof tool.inputSchema !== 'object') {
+          issues.push(`Tool "${tool.name}" inputSchema must be an object`);
+        }
+      }
+    } else if (manifest.tools !== undefined) {
+      issues.push('manifest.tools must be an array');
+    }
+
+    return { valid: issues.length === 0, issues, manifest };
+  }
+}

package/LeeWay-Standards/src/agents/mcp/port-agent.js

@@ -0,0 +1,125 @@
+/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: MCP.AGENT.PORT
+TAG: MCP.PORT.AGENT.MAIN
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=radio
+
+5WH:
+WHAT = Port agent — assigns and validates ports from a registry to prevent collisions
+WHY = Port collisions cause service startup failures; governance requires a centralized port registry
+WHO = Rapid Web Development
+WHERE = src/agents/mcp/port-agent.js
+WHEN = 2026
+HOW = Maintains a port registry in .leeway/ports.json, validates before assignment
+
+AGENTS:
+PORT
+ENDPOINT
+TRANSPORT
+
+LICENSE:
+MIT
+*/
+
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+const DEFAULT_PORT_RANGES = {
+  UI: [3000, 3099],
+  API: [4000, 4099],
+  AI: [5000, 5099],
+  MCP: [6000, 6099],
+  DATA: [7000, 7099],
+  UTIL: [8000, 8099],
+};
+
+/**
+ * PortAgent manages port assignments to prevent collisions.
+ */
+export class PortAgent {
+  constructor(options = {}) {
+    this.rootDir = options.rootDir || process.cwd();
+    this.registryPath = join(this.rootDir, '.leeway', 'ports.json');
+    this.registry = null;
+  }
+
+  async _loadRegistry() {
+    if (this.registry) return this.registry;
+    try {
+      const raw = await readFile(this.registryPath, 'utf8');
+      this.registry = JSON.parse(raw);
+    } catch {
+      this.registry = { assignments: {}, reserved: [22, 80, 443, 8080, 8443] };
+    }
+    return this.registry;
+  }
+
+  async _saveRegistry() {
+    await mkdir(join(this.rootDir, '.leeway'), { recursive: true });
+    await writeFile(this.registryPath, JSON.stringify(this.registry, null, 2), 'utf8');
+  }
+
+  /**
+   * Check if a port is available (not assigned).
+   *
+   * @param {number} port
+   * @returns {Promise<{ available: boolean, assignedTo?: string }>}
+   */
+  async checkPort(port) {
+    const reg = await this._loadRegistry();
+    const assignedTo = Object.entries(reg.assignments).find(([, p]) => p === port)?.[0];
+    const isReserved = reg.reserved.includes(port);
+
+    return {
+      available: !assignedTo && !isReserved,
+      assignedTo: assignedTo || (isReserved ? 'SYSTEM_RESERVED' : null),
+    };
+  }
+
+  /**
+   * Assign a port to a service.
+   *
+   * @param {string} serviceName
+   * @param {number} [preferredPort]
+   * @param {string} [region]
+   * @returns {Promise<{ port: number, assigned: boolean, conflict?: string }>}
+   */
+  async assignPort(serviceName, preferredPort, region = 'UTIL') {
+    const reg = await this._loadRegistry();
+
+    if (reg.assignments[serviceName]) {
+      return { port: reg.assignments[serviceName], assigned: false, reason: 'Already assigned' };
+    }
+
+    let port = preferredPort;
+    if (port) {
+      const check = await this.checkPort(port);
+      if (!check.available) {
+        return { port: null, assigned: false, conflict: `Port ${port} already assigned to ${check.assignedTo}` };
+      }
+    } else {
+      const [rangeStart, rangeEnd] = DEFAULT_PORT_RANGES[region] || DEFAULT_PORT_RANGES.UTIL;
+      for (let p = rangeStart; p <= rangeEnd; p++) {
+        const check = await this.checkPort(p);
+        if (check.available) { port = p; break; }
+      }
+    }
+
+    if (!port) {
+      return { port: null, assigned: false, reason: 'No available port in range' };
+    }
+
+    reg.assignments[serviceName] = port;
+    await this._saveRegistry();
+    return { port, assigned: true };
+  }
+}

package/LeeWay-Standards/src/agents/mcp/process-agent.js

@@ -0,0 +1,124 @@
+/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: MCP.AGENT.PROCESS
+TAG: MCP.PROCESS.AGENT.MAIN
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=cpu
+
+5WH:
+WHAT = Process agent — handles process ownership, shutdown sequencing, and zombie cleanup
+WHY = Unmanaged processes cause resource leaks, port conflicts, and failed restarts
+WHO = Rapid Web Development
+WHERE = src/agents/mcp/process-agent.js
+WHEN = 2026
+HOW = Tracks PID registry in .leeway/processes.json, validates liveness, signals shutdown
+
+AGENTS:
+PROCESS
+PORT
+HEALTH
+
+LICENSE:
+MIT
+*/
+
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * ProcessAgent tracks and manages process ownership and lifecycle.
+ */
+export class ProcessAgent {
+  constructor(options = {}) {
+    this.rootDir = options.rootDir || process.cwd();
+    this.registryPath = join(this.rootDir, '.leeway', 'processes.json');
+    this.registry = null;
+  }
+
+  async _load() {
+    if (this.registry) return this.registry;
+    try {
+      const raw = await readFile(this.registryPath, 'utf8');
+      this.registry = JSON.parse(raw);
+    } catch {
+      this.registry = { processes: {} };
+    }
+    return this.registry;
+  }
+
+  async _save() {
+    await mkdir(join(this.rootDir, '.leeway'), { recursive: true });
+    await writeFile(this.registryPath, JSON.stringify(this.registry, null, 2), 'utf8');
+  }
+
+  /**
+   * Register a process.
+   *
+   * @param {string} name - Process identifier
+   * @param {number} pid - OS process ID
+   * @param {object} [meta] - Additional metadata
+   */
+  async register(name, pid, meta = {}) {
+    const reg = await this._load();
+    reg.processes[name] = { pid, registered: new Date().toISOString(), ...meta };
+    await this._save();
+  }
+
+  /**
+   * Check if a process is alive.
+   *
+   * @param {string} name
+   * @returns {Promise<{ alive: boolean, pid: number | null }>}
+   */
+  async isAlive(name) {
+    const reg = await this._load();
+    const entry = reg.processes[name];
+    if (!entry) return { alive: false, pid: null };
+
+    try {
+      process.kill(entry.pid, 0);
+      return { alive: true, pid: entry.pid };
+    } catch {
+      return { alive: false, pid: entry.pid };
+    }
+  }
+
+  /**
+   * Clean up zombie entries (processes that are no longer alive).
+   * @returns {Promise<string[]>} - Names of cleaned processes
+   */
+  async cleanZombies() {
+    const reg = await this._load();
+    const cleaned = [];
+
+    for (const [name, entry] of Object.entries(reg.processes)) {
+      try {
+        process.kill(entry.pid, 0);
+      } catch {
+        delete reg.processes[name];
+        cleaned.push(name);
+      }
+    }
+
+    if (cleaned.length > 0) await this._save();
+    return cleaned;
+  }
+
+  /**
+   * Deregister a process entry.
+   * @param {string} name
+   */
+  async deregister(name) {
+    const reg = await this._load();
+    delete reg.processes[name];
+    await this._save();
+  }
+}