@agentlee5/agent-skills 1.0.0

package/LeeWay-Standards/src/cli/leeway.js

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: CORE.SDK.CLI
+TAG: CORE.SDK.CLI.LEEWAY
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=terminal
+
+5WH:
+WHAT = LEEWAY CLI — the primary command-line interface for the LEEWAY governance SDK
+WHY = Developers need a single command to run governance checks, audits, and repairs
+WHO = Rapid Web Development
+WHERE = src/cli/leeway.js
+WHEN = 2026
+HOW = Node.js CLI using process.argv, no heavy dependencies, direct agent invocation
+
+AGENTS:
+ASSESS
+ALIGN
+AUDIT
+DOCTOR
+REGISTRY
+
+LICENSE:
+MIT
+*/
+
+import { DoctorAgent } from '../agents/orchestration/doctor-agent.js';
+import { AuditAgent } from '../agents/governance/audit-agent.js';
+import { AssessAgent } from '../agents/governance/assess-agent.js';
+import { RegistryAgent } from '../agents/standards/registry-agent.js';
+import { ArchitectureMapAgent } from '../agents/discovery/architecture-map-agent.js';
+import { AlignAgent } from '../agents/governance/align-agent.js';
+import { SecretScanAgent } from '../agents/security/secret-scan-agent.js';
+import { readdir, readFile } from 'node:fs/promises';
+import { join, extname, relative } from 'node:path';
+
+const rootDir = process.cwd();
+const args = process.argv.slice(2);
+const command = args[0] || 'help';
+
+const BANNER = `
+  ██╗     ███████╗███████╗██╗    ██╗ █████╗ ██╗   ██╗
+  ██║     ██╔════╝██╔════╝██║    ██║██╔══██╗╚██╗ ██╔╝
+  ██║     █████╗  █████╗  ██║ █╗ ██║███████║ ╚████╔╝
+  ██║     ██╔══╝  ██╔══╝  ██║███╗██║██╔══██║  ╚██╔╝
+  ███████╗███████╗███████╗╚███╔███╔╝██║  ██║   ██║
+  ╚══════╝╚══════╝╚══════╝ ╚══╝╚══╝ ╚═╝  ╚═╝   ╚═╝
+  LEEWAY™ v1.0.1 — Autonomous Code Governance SDK
+`;
+
+const COMMANDS = {
+  doctor: 'Run full system health and compliance diagnosis',
+  audit: 'Score LEEWAY compliance across all code files',
+  assess: 'Survey what files and headers exist in the codebase',
+  align: 'Add missing LEEWAY headers (dry-run by default)',
+  registry: 'Build and save the LEEWAY file and tag registry',
+  map: 'Generate a codebase architecture map',
+  scan: 'Scan for hardcoded secrets',
+  help: 'Show this help message',
+};
+
+async function runDoctor() {
+  console.log(BANNER);
+  console.log('Running LEEWAY Doctor...\n');
+  const agent = new DoctorAgent({ rootDir });
+  const report = await agent.run();
+  console.log(agent.formatReport(report));
+  process.exit(report.healthy ? 0 : 1);
+}
+
+async function runAudit() {
+  console.log(BANNER);
+  console.log('Running LEEWAY Audit...\n');
+  const agent = new AuditAgent({ rootDir });
+  const report = await agent.runAndSave();
+  console.log(agent._formatTextReport(report));
+  if (report.savedTo) {
+    console.log(`\n📄 Reports saved to:\n  JSON: ${report.savedTo.json}\n  Text: ${report.savedTo.text}`);
+  }
+  process.exit(report.summary.averageScore >= 60 ? 0 : 1);
+}
+
+async function runAssess() {
+  console.log(BANNER);
+  console.log('Running LEEWAY Assessment...\n');
+  const agent = new AssessAgent({ rootDir });
+  const result = await agent.run();
+  console.log('── ASSESSMENT SUMMARY ─────────────────────────────');
+  console.log(`  Total Files      : ${result.inventory.totalFiles}`);
+  console.log(`  Code Files       : ${result.inventory.codeFiles}`);
+  console.log(`  Header Coverage  : ${result.summary.headerCoverage}`);
+  console.log(`  Missing Headers  : ${result.summary.filesNeedingHeaders}`);
+  console.log(`  Duplicate Tags   : ${result.summary.duplicateTagCount}`);
+  console.log(`  Regions Found    : ${result.summary.regionsFound}`);
+
+  if (result.inventory.missingHeaders.length > 0) {
+    console.log('\n── FILES MISSING HEADERS (first 10) ───────────────');
+    result.inventory.missingHeaders.slice(0, 10).forEach(f => console.log(`  ⚠️  ${f}`));
+  }
+  if (result.inventory.duplicateTags.length > 0) {
+    console.log('\n── DUPLICATE TAGS ──────────────────────────────────');
+    result.inventory.duplicateTags.forEach(d => {
+      console.log(`  ⚠️  ${d.tag}`);
+      d.files.forEach(f => console.log(`      → ${f}`));
+    });
+  }
+}
+
+async function runAlign() {
+  const dryRun = !args.includes('--apply');
+  console.log(BANNER);
+  console.log(`Running LEEWAY Align (${dryRun ? 'DRY RUN — use --apply to write changes' : 'APPLYING CHANGES'})...\n`);
+
+  const assessAgent = new AssessAgent({ rootDir });
+  const assessment = await assessAgent.run();
+  const missing = assessment.inventory.missingHeaders;
+
+  if (missing.length === 0) {
+    console.log('✅ All code files have LEEWAY headers. Nothing to align.');
+    return;
+  }
+
+  const alignAgent = new AlignAgent({ rootDir, dryRun });
+  const result = await alignAgent.alignHeaders(missing);
+
+  console.log(`Processed ${result.processed} files`);
+  result.results.forEach(r => {
+    const icon = r.action === 'header_added' ? '✅' : r.action === 'error' ? '❌' : '⏭️ ';
+    console.log(`  ${icon} [${r.action}] ${r.file}`);
+  });
+
+  if (dryRun && result.results.some(r => r.action === 'header_added')) {
+    console.log('\n💡 Run with --apply to write changes: leeway align --apply');
+  }
+}
+
+async function runRegistry() {
+  console.log(BANNER);
+  console.log('Building LEEWAY Registry...\n');
+  const agent = new RegistryAgent({ rootDir });
+  const registry = await agent.buildAndSave();
+  console.log(`✅ Registry built: ${Object.keys(registry.files).length} files indexed`);
+  console.log(`   Tags found: ${Object.keys(registry.tags).length}`);
+  console.log(`   Regions: ${Object.keys(registry.regions).join(', ')}`);
+  if (registry.savedTo) console.log(`   Saved to: ${registry.savedTo}`);
+}
+
+async function runMap() {
+  console.log(BANNER);
+  console.log('Building Architecture Map...\n');
+  const agent = new ArchitectureMapAgent({ rootDir });
+  const ascii = await agent.buildAsciiDiagram();
+  console.log(ascii);
+}
+
+async function runScan() {
+  console.log(BANNER);
+  console.log('Scanning for secrets...\n');
+  const agent = new SecretScanAgent({ rootDir });
+  const CODE_EXTENSIONS = new Set(['.js', '.ts', '.jsx', '.tsx', '.mjs', '.cjs', '.env', '.json', '.yaml', '.yml']);
+  const SKIP_DIRS = new Set(['.git', 'node_modules', 'dist', 'build', '.next', 'coverage']);
+
+  let totalFindings = 0;
+  const walk = async (dir, depth = 0) => {
+    if (depth > 8) return;
+    let entries;
+    try { entries = await readdir(dir, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      const fullPath = join(dir, entry.name);
+      if (entry.isDirectory()) { await walk(fullPath, depth + 1); }
+      else if (CODE_EXTENSIONS.has(extname(entry.name))) {
+        const result = await agent.scanFile(fullPath);
+        if (!result.clean) {
+          totalFindings += result.findings.length;
+          console.log(`\n❌ ${relative(rootDir, fullPath)}`);
+          result.findings.forEach(f => console.log(`   Line ${f.line}: [${f.rule}] ${f.label}`));
+        }
+      }
+    }
+  };
+  await walk(rootDir);
+
+  if (totalFindings === 0) {
+    console.log('✅ No secrets detected');
+  } else {
+    console.log(`\n⚠️  ${totalFindings} potential secret(s) found. Review and remediate immediately.`);
+    process.exit(1);
+  }
+}
+
+function showHelp() {
+  console.log(BANNER);
+  console.log('Usage: leeway <command> [options]\n');
+  console.log('Commands:');
+  for (const [cmd, desc] of Object.entries(COMMANDS)) {
+    console.log(`  ${cmd.padEnd(12)} ${desc}`);
+  }
+  console.log('\nOptions:');
+  console.log('  --apply      Apply changes (used with align command)');
+  console.log('  --help       Show this help message');
+  console.log('');
+}
+
+switch (command) {
+  case 'doctor':   await runDoctor();   break;
+  case 'audit':    await runAudit();    break;
+  case 'assess':   await runAssess();   break;
+  case 'align':    await runAlign();    break;
+  case 'registry': await runRegistry(); break;
+  case 'map':      await runMap();      break;
+  case 'scan':     await runScan();     break;
+  case 'help':
+  case '--help':
+  default:         showHelp();          break;
+}

package/LeeWay-Standards/src/core/compliance-scorer.js

@@ -0,0 +1,168 @@
+/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: CORE.SDK.SCORER
+TAG: CORE.SDK.COMPLIANCE.SCORER
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=bar-chart-2
+
+5WH:
+WHAT = Scores LEEWAY compliance for files, directories, and repositories
+WHY = The LEEWAY system must be able to quantify how well a codebase follows governance standards
+WHO = Rapid Web Development
+WHERE = src/core/compliance-scorer.js
+WHEN = 2026
+HOW = Weighted scoring across header, tag, placement, security, and naming rules
+
+AGENTS:
+AUDIT
+ASSESS
+DOCTOR
+
+LICENSE:
+MIT
+*/
+
+import { parseHeader, validateHeader } from './header-parser.js';
+import { validateTag } from './tag-validator.js';
+import { classifyRegion } from './region-classifier.js';
+
+export const COMPLIANCE_LEVELS = {
+  PLATINUM: { min: 95, label: 'Platinum', description: 'Fully LEEWAY-compliant' },
+  GOLD: { min: 80, label: 'Gold', description: 'Mostly compliant, minor gaps' },
+  SILVER: { min: 60, label: 'Silver', description: 'Partially compliant, moderate gaps' },
+  BRONZE: { min: 40, label: 'Bronze', description: 'Minimal compliance, major gaps' },
+  NONE: { min: 0, label: 'None', description: 'Not LEEWAY-compliant' },
+};
+
+const SCORE_WEIGHTS = {
+  hasHeader: 30,
+  headerValid: 20,
+  tagValid: 15,
+  regionDeclared: 10,
+  namingConvention: 10,
+  correctPlacement: 10,
+  securityCompliant: 5,
+};
+
+/**
+ * Score the LEEWAY compliance of a single file.
+ *
+ * @param {{ filePath: string, content: string }} file
+ * @returns {{ score: number, level: string, breakdown: object, issues: string[] }}
+ */
+export function scoreCompliance(file) {
+  const { filePath = '', content = '' } = file;
+  const breakdown = {};
+  const issues = [];
+  let totalScore = 0;
+
+  const header = parseHeader(content);
+  const hasHeader = header !== null;
+  breakdown.hasHeader = hasHeader ? SCORE_WEIGHTS.hasHeader : 0;
+  totalScore += breakdown.hasHeader;
+  if (!hasHeader) issues.push('Missing LEEWAY header block');
+
+  if (hasHeader) {
+    const { valid: headerValid, errors: headerErrors } = validateHeader(header);
+    breakdown.headerValid = headerValid ? SCORE_WEIGHTS.headerValid : Math.round(SCORE_WEIGHTS.headerValid * (1 - headerErrors.length / 7));
+    totalScore += breakdown.headerValid;
+    if (!headerValid) issues.push(...headerErrors);
+
+    if (header.tag) {
+      const { valid: tagValid, errors: tagErrors } = validateTag(header.tag);
+      breakdown.tagValid = tagValid ? SCORE_WEIGHTS.tagValid : 0;
+      totalScore += breakdown.tagValid;
+      if (!tagValid) issues.push(...tagErrors);
+    } else {
+      breakdown.tagValid = 0;
+    }
+
+    breakdown.regionDeclared = header.region ? SCORE_WEIGHTS.regionDeclared : 0;
+    totalScore += breakdown.regionDeclared;
+    if (!header.region) issues.push('Missing REGION declaration');
+  } else {
+    breakdown.headerValid = 0;
+    breakdown.tagValid = 0;
+    breakdown.regionDeclared = 0;
+  }
+
+  const namingScore = checkNamingConvention(filePath);
+  breakdown.namingConvention = namingScore ? SCORE_WEIGHTS.namingConvention : 0;
+  totalScore += breakdown.namingConvention;
+  if (!namingScore) issues.push(`File naming convention violation: ${filePath}`);
+
+  const placementScore = checkPlacement(filePath, header);
+  breakdown.correctPlacement = placementScore ? SCORE_WEIGHTS.correctPlacement : 0;
+  totalScore += breakdown.correctPlacement;
+  if (!placementScore) issues.push(`File placement may be incorrect for region`);
+
+  const securityScore = checkSecurity(content);
+  breakdown.securityCompliant = securityScore ? SCORE_WEIGHTS.securityCompliant : 0;
+  totalScore += breakdown.securityCompliant;
+  if (!securityScore) issues.push('Potential security violation detected (secrets/credentials)');
+
+  const score = Math.min(100, Math.max(0, totalScore));
+  const level = getComplianceLevel(score);
+
+  return { score, level, breakdown, issues };
+}
+
+function checkNamingConvention(filePath) {
+  if (!filePath) return false;
+  const path = filePath.replace(/\\/g, '/');
+  const segments = path.split('/');
+  const fileName = segments[segments.length - 1] || '';
+
+  const isPascalCase = /^[A-Z][a-zA-Z0-9]*(\.[a-z]+)+$/.test(fileName);
+  const isCamelCase = /^[a-z][a-zA-Z0-9]*(\.[a-z]+)+$/.test(fileName);
+  const isKebabCase = /^[a-z][a-z0-9-]*(\.[a-z]+)+$/.test(fileName);
+
+  return isPascalCase || isCamelCase || isKebabCase;
+}
+
+function checkPlacement(filePath, header) {
+  if (!filePath || !header || !header.region) return true;
+  const path = filePath.toLowerCase().replace(/\\/g, '/');
+  const region = header.region.split('.')[0];
+
+  const regionPathMap = {
+    UI: ['components', 'pages', 'layouts', 'ui', 'views'],
+    CORE: ['core', 'sdk', 'lib', 'runtime'],
+    DATA: ['data', 'store', 'db', 'models'],
+    AI: ['ai', 'agents', 'llm', 'ml'],
+    SEO: ['seo', 'discovery', 'schema'],
+    UTIL: ['utils', 'helpers', 'util'],
+    MCP: ['mcp', 'transport'],
+    SECURITY: ['security', 'auth'],
+  };
+
+  const expectedPaths = regionPathMap[region];
+  if (!expectedPaths) return true;
+
+  return expectedPaths.some(p => path.includes(`/${p}/`));
+}
+
+function checkSecurity(content) {
+  if (!content) return true;
+  const secretPatterns = [
+    /(?:password|passwd|secret|api[_-]?key|token|credential)\s*[:=]\s*['"][^'"]{8,}/i,
+    /(?:sk-|pk-)[a-zA-Z0-9]{20,}/,
+    /[a-zA-Z0-9._%+-]+:[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-z]{2,}/,
+  ];
+  return !secretPatterns.some(pattern => pattern.test(content));
+}
+
+function getComplianceLevel(score) {
+  for (const [level, data] of Object.entries(COMPLIANCE_LEVELS)) {
+    if (score >= data.min) return level;
+  }
+  return 'NONE';
+}

package/LeeWay-Standards/src/core/compliance-scorer.test.js

@@ -0,0 +1,121 @@
+/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: TEST.CORE.COMPLIANCE
+TAG: TEST.UNIT.COMPLIANCE.SCORER
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=test-tube
+
+5WH:
+WHAT = Unit tests for the LEEWAY compliance-scorer core module
+WHY = Compliance scoring drives audit reports and governance gates
+WHO = Rapid Web Development
+WHERE = src/core/compliance-scorer.test.js
+WHEN = 2026
+HOW = Node.js built-in test runner (node:test) with assert
+
+AGENTS:
+AUDIT
+
+LICENSE:
+MIT
+*/
+
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { scoreCompliance, COMPLIANCE_LEVELS } from './compliance-scorer.js';
+
+const COMPLIANT_CONTENT = `/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: CORE.SDK.TEST
+TAG: CORE.SDK.TEST.MAIN
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=file
+
+5WH:
+WHAT = Test module
+WHY = For compliance scoring tests
+WHO = Test Author
+WHERE = src/core/test.js
+WHEN = 2026
+HOW = Node.js
+
+AGENTS:
+ASSESS
+
+LICENSE:
+MIT
+*/
+
+export function test() {}
+`;
+
+const NON_COMPLIANT_CONTENT = `export function test() {}`;
+
+describe('COMPLIANCE_LEVELS', () => {
+  test('exports all compliance levels', () => {
+    const required = ['PLATINUM', 'GOLD', 'SILVER', 'BRONZE', 'NONE'];
+    for (const level of required) {
+      assert.ok(COMPLIANCE_LEVELS[level], `Should have level: ${level}`);
+    }
+  });
+
+  test('levels have min and label', () => {
+    for (const [key, level] of Object.entries(COMPLIANCE_LEVELS)) {
+      assert.ok(typeof level.min === 'number', `${key} should have numeric min`);
+      assert.ok(typeof level.label === 'string', `${key} should have label`);
+    }
+  });
+});
+
+describe('scoreCompliance', () => {
+  test('scores a compliant file highly', () => {
+    const result = scoreCompliance({ filePath: 'src/core/test.js', content: COMPLIANT_CONTENT });
+    assert.ok(result.score >= 70, `Expected score >= 70, got ${result.score}`);
+    assert.ok(['PLATINUM', 'GOLD', 'SILVER'].includes(result.level));
+  });
+
+  test('scores a non-compliant file low', () => {
+    const result = scoreCompliance({ filePath: 'src/test.js', content: NON_COMPLIANT_CONTENT });
+    assert.ok(result.score < 60, `Expected score < 60, got ${result.score}`);
+  });
+
+  test('reports missing header as an issue', () => {
+    const result = scoreCompliance({ filePath: 'src/test.js', content: NON_COMPLIANT_CONTENT });
+    assert.ok(result.issues.some(i => i.toLowerCase().includes('header')));
+  });
+
+  test('returns breakdown object', () => {
+    const result = scoreCompliance({ filePath: 'src/core/test.js', content: COMPLIANT_CONTENT });
+    assert.ok(typeof result.breakdown === 'object');
+    assert.ok('hasHeader' in result.breakdown);
+  });
+
+  test('score is between 0 and 100', () => {
+    const r1 = scoreCompliance({ filePath: 'src/test.js', content: NON_COMPLIANT_CONTENT });
+    const r2 = scoreCompliance({ filePath: 'src/core/test.js', content: COMPLIANT_CONTENT });
+    assert.ok(r1.score >= 0 && r1.score <= 100);
+    assert.ok(r2.score >= 0 && r2.score <= 100);
+  });
+
+  test('detects potential secrets', () => {
+    const content = COMPLIANT_CONTENT + '\nconst apiKey = "sk-abcdefghijklmnopqrstuvwxyz12345678";';
+    const result = scoreCompliance({ filePath: 'src/core/test.js', content });
+    assert.ok(result.issues.some(i => i.toLowerCase().includes('security')));
+  });
+});