@agentlee5/agent-skills 1.0.0

package/LeeWay-Standards/src/core/header-parser.js

@@ -0,0 +1,207 @@
+/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: CORE.SDK.PARSER
+TAG: CORE.SDK.HEADER.PARSER
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=file-text
+
+5WH:
+WHAT = Parses, validates, and builds LEEWAY identity headers from source files
+WHY = Every LEEWAY-compliant file must begin with a structured identity header; this module reads and writes those headers
+WHO = Rapid Web Development
+WHERE = src/core/header-parser.js
+WHEN = 2026
+HOW = Pure JS string parsing, no regex over-engineering, line-by-line state machine
+
+AGENTS:
+HEADER
+ASSESS
+AUDIT
+
+LICENSE:
+MIT
+*/
+
+const HEADER_START = 'LEEWAY HEADER — DO NOT REMOVE';
+const HEADER_END_MARKER = '*/';
+const REQUIRED_FIELDS = ['REGION', 'TAG', '5WH', 'LICENSE'];
+const REQUIRED_5WH = ['WHAT', 'WHY', 'WHO', 'WHERE', 'WHEN', 'HOW'];
+
+/**
+ * Parse a LEEWAY header block from file content.
+ * Returns a structured object or null if no valid header found.
+ *
+ * @param {string} content - Raw file content
+ * @returns {{ region: string, tag: string, colorOnionHex: object, iconAscii: object, fiveWH: object, agents: string[], license: string } | null}
+ */
+export function parseHeader(content) {
+  if (typeof content !== 'string') return null;
+
+  const startIdx = content.indexOf(HEADER_START);
+  if (startIdx === -1) return null;
+
+  const endIdx = content.indexOf(HEADER_END_MARKER, startIdx);
+  if (endIdx === -1) return null;
+
+  const block = content.slice(startIdx, endIdx).trim();
+  const lines = block.split('\n').map(l => l.trim()).filter(Boolean);
+
+  const result = {
+    region: null,
+    tag: null,
+    colorOnionHex: {},
+    iconAscii: {},
+    fiveWH: {},
+    agents: [],
+    license: null,
+  };
+
+  let section = null;
+
+  for (const line of lines) {
+    if (line === HEADER_START) continue;
+
+    if (line.startsWith('REGION:')) {
+      result.region = line.slice('REGION:'.length).trim();
+      section = null;
+      continue;
+    }
+    if (line.startsWith('TAG:')) {
+      result.tag = line.slice('TAG:'.length).trim();
+      section = null;
+      continue;
+    }
+    if (line === 'COLOR_ONION_HEX:') { section = 'color'; continue; }
+    if (line === 'ICON_ASCII:') { section = 'icon'; continue; }
+    if (line === '5WH:') { section = '5wh'; continue; }
+    if (line === 'AGENTS:') { section = 'agents'; continue; }
+    if (line === 'LICENSE:') { section = 'license'; continue; }
+
+    switch (section) {
+      case 'color': {
+        const [key, val] = line.split('=');
+        if (key && val) result.colorOnionHex[key.trim()] = val.trim();
+        break;
+      }
+      case 'icon': {
+        const [key, val] = line.split('=');
+        if (key && val) result.iconAscii[key.trim()] = val.trim();
+        break;
+      }
+      case '5wh': {
+        const eqIdx = line.indexOf('=');
+        if (eqIdx !== -1) {
+          const key = line.slice(0, eqIdx).trim();
+          const val = line.slice(eqIdx + 1).trim();
+          result.fiveWH[key] = val;
+        }
+        break;
+      }
+      case 'agents': {
+        if (line) result.agents.push(line.trim());
+        break;
+      }
+      case 'license': {
+        if (line) result.license = line.trim();
+        break;
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Validate a parsed LEEWAY header object.
+ * Returns { valid: boolean, errors: string[] }
+ *
+ * @param {object} header - Result from parseHeader()
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateHeader(header) {
+  const errors = [];
+
+  if (!header) {
+    return { valid: false, errors: ['No LEEWAY header found'] };
+  }
+
+  if (!header.region) errors.push('Missing REGION');
+  if (!header.tag) errors.push('Missing TAG');
+  if (!header.license) errors.push('Missing LICENSE');
+
+  for (const field of REQUIRED_5WH) {
+    if (!header.fiveWH[field]) {
+      errors.push(`Missing 5WH field: ${field}`);
+    }
+  }
+
+  if (header.tag) {
+    const tagParts = header.tag.split('.');
+    if (tagParts.length < 3) {
+      errors.push('TAG must follow DOMAIN.SUBDOMAIN.ASSET.PURPOSE format (minimum 3 parts)');
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Build a LEEWAY header comment block from a header config object.
+ *
+ * @param {object} config - Header fields
+ * @param {string} config.region
+ * @param {string} config.tag
+ * @param {object} [config.colorOnionHex]
+ * @param {object} [config.iconAscii]
+ * @param {object} config.fiveWH
+ * @param {string[]} [config.agents]
+ * @param {string} [config.license]
+ * @returns {string} - Complete header comment block
+ */
+export function buildHeader(config) {
+  const {
+    region,
+    tag,
+    colorOnionHex = { NEON: '#39FF14', FLUO: '#0DFF94', PASTEL: '#C7FFD8' },
+    iconAscii = { family: 'lucide', glyph: 'file' },
+    fiveWH = {},
+    agents = [],
+    license = 'MIT',
+  } = config;
+
+  const colorLines = Object.entries(colorOnionHex).map(([k, v]) => `${k}=${v}`).join('\n');
+  const iconLines = Object.entries(iconAscii).map(([k, v]) => `${k}=${v}`).join('\n');
+  const wh5Lines = REQUIRED_5WH.map(k => `${k} = ${fiveWH[k] || '(not set)'}`).join('\n');
+  const agentLines = agents.join('\n');
+
+  return `/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: ${region}
+TAG: ${tag}
+
+COLOR_ONION_HEX:
+${colorLines}
+
+ICON_ASCII:
+${iconLines}
+
+5WH:
+${wh5Lines}
+
+AGENTS:
+${agentLines}
+
+LICENSE:
+${license}
+*/
+`;
+}

package/LeeWay-Standards/src/core/header-parser.test.js

@@ -0,0 +1,198 @@
+/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: TEST.CORE.HEADER
+TAG: TEST.UNIT.HEADER.PARSER
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=test-tube
+
+5WH:
+WHAT = Unit tests for the LEEWAY header-parser core module
+WHY = The header parser is foundational — every other module depends on it working correctly
+WHO = Rapid Web Development
+WHERE = src/core/header-parser.test.js
+WHEN = 2026
+HOW = Node.js built-in test runner (node:test) with assert
+
+AGENTS:
+AUDIT
+ASSESS
+
+LICENSE:
+MIT
+*/
+
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { parseHeader, validateHeader, buildHeader } from './header-parser.js';
+
+const SAMPLE_HEADER_CONTENT = `/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: UI.COMPONENT.NEXUS
+TAG: UI.COMPONENT.NEXUS.BUTTON
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=layout-dashboard
+
+5WH:
+WHAT = Nexus button component
+WHY = Primary voice control interface
+WHO = Rapid Web Development
+WHERE = src/components/NexusButton.tsx
+WHEN = 2026
+HOW = React + Tailwind
+
+AGENTS:
+AZR
+PHI3
+
+LICENSE:
+MIT
+*/
+
+export function NexusButton() {}
+`;
+
+const NO_HEADER_CONTENT = `export function NexusButton() {}`;
+
+describe('parseHeader', () => {
+  test('parses a valid LEEWAY header', () => {
+    const result = parseHeader(SAMPLE_HEADER_CONTENT);
+    assert.ok(result, 'Should return an object');
+    assert.equal(result.region, 'UI.COMPONENT.NEXUS');
+    assert.equal(result.tag, 'UI.COMPONENT.NEXUS.BUTTON');
+    assert.equal(result.license, 'MIT');
+    assert.deepEqual(result.agents, ['AZR', 'PHI3']);
+  });
+
+  test('returns null when no header is present', () => {
+    const result = parseHeader(NO_HEADER_CONTENT);
+    assert.equal(result, null);
+  });
+
+  test('returns null for non-string input', () => {
+    assert.equal(parseHeader(null), null);
+    assert.equal(parseHeader(undefined), null);
+    assert.equal(parseHeader(42), null);
+  });
+
+  test('parses 5WH fields correctly', () => {
+    const result = parseHeader(SAMPLE_HEADER_CONTENT);
+    assert.ok(result.fiveWH);
+    assert.equal(result.fiveWH.WHAT, 'Nexus button component');
+    assert.equal(result.fiveWH.WHY, 'Primary voice control interface');
+    assert.equal(result.fiveWH.WHO, 'Rapid Web Development');
+    assert.equal(result.fiveWH.WHEN, '2026');
+  });
+
+  test('parses color hex values', () => {
+    const result = parseHeader(SAMPLE_HEADER_CONTENT);
+    assert.equal(result.colorOnionHex.NEON, '#39FF14');
+    assert.equal(result.colorOnionHex.FLUO, '#0DFF94');
+  });
+
+  test('parses icon ascii fields', () => {
+    const result = parseHeader(SAMPLE_HEADER_CONTENT);
+    assert.equal(result.iconAscii.family, 'lucide');
+    assert.equal(result.iconAscii.glyph, 'layout-dashboard');
+  });
+});
+
+describe('validateHeader', () => {
+  test('validates a complete header as valid', () => {
+    const header = parseHeader(SAMPLE_HEADER_CONTENT);
+    const { valid, errors } = validateHeader(header);
+    assert.equal(valid, true);
+    assert.equal(errors.length, 0);
+  });
+
+  test('returns error for null header', () => {
+    const { valid, errors } = validateHeader(null);
+    assert.equal(valid, false);
+    assert.ok(errors.length > 0);
+  });
+
+  test('reports missing REGION', () => {
+    const { valid, errors } = validateHeader({ tag: 'UI.COMPONENT.X.Y', license: 'MIT', fiveWH: { WHAT: 'x', WHY: 'y', WHO: 'z', WHERE: 'a', WHEN: '2026', HOW: 'b' } });
+    assert.equal(valid, false);
+    assert.ok(errors.some(e => e.includes('REGION')));
+  });
+
+  test('reports missing 5WH fields', () => {
+    const { valid, errors } = validateHeader({ region: 'UI', tag: 'UI.X.Y', license: 'MIT', fiveWH: {} });
+    assert.equal(valid, false);
+    assert.ok(errors.some(e => e.includes('WHAT')));
+  });
+
+  test('reports invalid TAG format', () => {
+    const { valid, errors } = validateHeader({
+      region: 'UI',
+      tag: 'BADTAG',
+      license: 'MIT',
+      fiveWH: { WHAT: 'x', WHY: 'y', WHO: 'z', WHERE: 'a', WHEN: '2026', HOW: 'b' },
+    });
+    assert.equal(valid, false);
+    assert.ok(errors.some(e => e.toLowerCase().includes('tag')));
+  });
+});
+
+describe('buildHeader', () => {
+  test('builds a valid header string', () => {
+    const header = buildHeader({
+      region: 'UI.COMPONENT.TEST',
+      tag: 'UI.COMPONENT.TEST.MAIN',
+      fiveWH: {
+        WHAT: 'Test component',
+        WHY: 'For testing',
+        WHO: 'Test Author',
+        WHERE: 'src/test.js',
+        WHEN: '2026',
+        HOW: 'Node.js',
+      },
+      agents: ['ASSESS'],
+      license: 'MIT',
+    });
+
+    assert.ok(typeof header === 'string');
+    assert.ok(header.includes('LEEWAY HEADER — DO NOT REMOVE'));
+    assert.ok(header.includes('REGION: UI.COMPONENT.TEST'));
+    assert.ok(header.includes('TAG: UI.COMPONENT.TEST.MAIN'));
+    assert.ok(header.includes('MIT'));
+    assert.ok(header.includes('ASSESS'));
+  });
+
+  test('built header is parseable', () => {
+    const header = buildHeader({
+      region: 'CORE.SDK.TEST',
+      tag: 'CORE.SDK.TEST.UNIT',
+      fiveWH: {
+        WHAT: 'Test',
+        WHY: 'Testing',
+        WHO: 'Dev',
+        WHERE: 'test.js',
+        WHEN: '2026',
+        HOW: 'Node',
+      },
+    });
+
+    const content = header + '\nexport default {};';
+    const parsed = parseHeader(content);
+    assert.ok(parsed);
+    assert.equal(parsed.region, 'CORE.SDK.TEST');
+    assert.equal(parsed.tag, 'CORE.SDK.TEST.UNIT');
+  });
+});

package/LeeWay-Standards/src/core/region-classifier.js

@@ -0,0 +1,137 @@
+/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: CORE.SDK.CLASSIFIER
+TAG: CORE.SDK.REGION.CLASSIFIER
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=map-pin
+
+5WH:
+WHAT = Classifies files into LEEWAY system regions
+WHY = Every file must belong to a named region that defines its role and layer in the system
+WHO = Rapid Web Development
+WHERE = src/core/region-classifier.js
+WHEN = 2026
+HOW = Path-based heuristics with configurable overrides
+
+AGENTS:
+REGION
+ASSESS
+
+LICENSE:
+MIT
+*/
+
+/**
+ * All recognized LEEWAY system regions with metadata.
+ */
+export const REGIONS = {
+  UI: {
+    label: 'User Interface',
+    description: 'User interface components, pages, layouts, and styling',
+    color: '#39FF14',
+    paths: ['components', 'pages', 'layouts', 'ui', 'views', 'screens', 'styles', 'themes'],
+  },
+  CORE: {
+    label: 'Core System',
+    description: 'Core system logic, runtime, configuration, and SDK internals',
+    color: '#FF6B35',
+    paths: ['core', 'sdk', 'runtime', 'engine', 'config', 'lib'],
+  },
+  DATA: {
+    label: 'Data Storage',
+    description: 'Storage, database access, models, caches, and migrations',
+    color: '#4ECDC4',
+    paths: ['data', 'store', 'stores', 'db', 'database', 'models', 'migrations', 'cache'],
+  },
+  AI: {
+    label: 'AI Orchestration',
+    description: 'AI orchestration, models, prompts, agents, and memory',
+    color: '#A855F7',
+    paths: ['ai', 'agents', 'llm', 'ml', 'prompts', 'models', 'memory', 'orchestration'],
+  },
+  SEO: {
+    label: 'Search & Discovery',
+    description: 'SEO, structured data, sitemaps, and discovery metadata',
+    color: '#F59E0B',
+    paths: ['seo', 'discovery', 'schema', 'sitemap', 'metadata', 'structured-data'],
+  },
+  UTIL: {
+    label: 'Utilities',
+    description: 'Utility functions, formatters, helpers, and shared tools',
+    color: '#6B7280',
+    paths: ['utils', 'util', 'helpers', 'shared', 'common', 'tools'],
+  },
+  MCP: {
+    label: 'Multi-Component Processing',
+    description: 'MCP transport, endpoints, ports, processes, and manifests',
+    color: '#0EA5E9',
+    paths: ['mcp', 'transport', 'endpoints', 'ports', 'processes', 'manifests'],
+  },
+  SECURITY: {
+    label: 'Security',
+    description: 'Security, authentication, authorization, and policy enforcement',
+    color: '#EF4444',
+    paths: ['security', 'auth', 'authentication', 'authorization', 'policies', 'permissions'],
+  },
+  TEST: {
+    label: 'Testing',
+    description: 'Unit tests, integration tests, fixtures, and mocks',
+    color: '#10B981',
+    paths: ['test', 'tests', '__tests__', 'spec', 'specs', 'fixtures', 'mocks'],
+  },
+  DOCS: {
+    label: 'Documentation',
+    description: 'Standards documents, guides, schemas, and reports',
+    color: '#8B5CF6',
+    paths: ['docs', 'documentation', 'guides', 'reports', 'schemas', 'examples'],
+  },
+};
+
+/**
+ * Classify a file into a LEEWAY region based on its path.
+ *
+ * @param {string} filePath - Relative or absolute file path
+ * @returns {{ region: string, confidence: 'high' | 'medium' | 'low', metadata: object }}
+ */
+export function classifyRegion(filePath) {
+  if (!filePath || typeof filePath !== 'string') {
+    return { region: 'CORE', confidence: 'low', metadata: REGIONS.CORE };
+  }
+
+  const path = filePath.toLowerCase().replace(/\\/g, '/');
+  const segments = path.split('/').filter(Boolean);
+
+  for (const [regionKey, regionData] of Object.entries(REGIONS)) {
+    for (const pattern of regionData.paths) {
+      if (segments.includes(pattern)) {
+        return {
+          region: regionKey,
+          confidence: 'high',
+          metadata: regionData,
+        };
+      }
+    }
+  }
+
+  for (const [regionKey, regionData] of Object.entries(REGIONS)) {
+    for (const pattern of regionData.paths) {
+      if (path.includes(pattern)) {
+        return {
+          region: regionKey,
+          confidence: 'medium',
+          metadata: regionData,
+        };
+      }
+    }
+  }
+
+  return { region: 'CORE', confidence: 'low', metadata: REGIONS.CORE };
+}

package/LeeWay-Standards/src/core/region-classifier.test.js

@@ -0,0 +1,100 @@
+/*
+LEEWAY HEADER — DO NOT REMOVE
+
+REGION: TEST.CORE.REGION
+TAG: TEST.UNIT.REGION.CLASSIFIER
+
+COLOR_ONION_HEX:
+NEON=#39FF14
+FLUO=#0DFF94
+PASTEL=#C7FFD8
+
+ICON_ASCII:
+family=lucide
+glyph=test-tube
+
+5WH:
+WHAT = Unit tests for the LEEWAY region-classifier core module
+WHY = Region classification determines where files belong; errors affect entire governance pipeline
+WHO = Rapid Web Development
+WHERE = src/core/region-classifier.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 { classifyRegion, REGIONS } from './region-classifier.js';
+
+describe('REGIONS', () => {
+  test('exports all required regions', () => {
+    const required = ['UI', 'CORE', 'DATA', 'AI', 'SEO', 'UTIL', 'MCP', 'SECURITY', 'TEST', 'DOCS'];
+    for (const r of required) {
+      assert.ok(REGIONS[r], `Should have region: ${r}`);
+    }
+  });
+
+  test('each region has required metadata', () => {
+    for (const [key, region] of Object.entries(REGIONS)) {
+      assert.ok(region.label, `${key} should have label`);
+      assert.ok(region.description, `${key} should have description`);
+      assert.ok(region.color, `${key} should have color`);
+      assert.ok(Array.isArray(region.paths), `${key} should have paths array`);
+    }
+  });
+});
+
+describe('classifyRegion', () => {
+  test('classifies UI component paths', () => {
+    const { region } = classifyRegion('src/components/NexusButton.tsx');
+    assert.equal(region, 'UI');
+  });
+
+  test('classifies AI agent paths', () => {
+    const { region } = classifyRegion('src/agents/assess-agent.js');
+    assert.equal(region, 'AI');
+  });
+
+  test('classifies DATA paths', () => {
+    const { region } = classifyRegion('src/data/userStore.js');
+    assert.equal(region, 'DATA');
+  });
+
+  test('classifies SECURITY paths', () => {
+    const { region } = classifyRegion('src/security/validator.js');
+    assert.equal(region, 'SECURITY');
+  });
+
+  test('classifies UTIL paths', () => {
+    const { region } = classifyRegion('src/utils/formatDate.js');
+    assert.equal(region, 'UTIL');
+  });
+
+  test('classifies DOCS paths', () => {
+    const { region } = classifyRegion('docs/standards.md');
+    assert.equal(region, 'DOCS');
+  });
+
+  test('returns CORE as fallback for unknown paths', () => {
+    const { region } = classifyRegion('unknown/something.js');
+    assert.equal(region, 'CORE');
+  });
+
+  test('handles null/empty paths gracefully', () => {
+    const { region } = classifyRegion(null);
+    assert.equal(region, 'CORE');
+    const { region: r2 } = classifyRegion('');
+    assert.equal(r2, 'CORE');
+  });
+
+  test('returns confidence level', () => {
+    const { confidence } = classifyRegion('src/components/Button.tsx');
+    assert.ok(['high', 'medium', 'low'].includes(confidence));
+  });
+});