@8lys/core

@8lys/core

Core utilities and configuration management for the 8LYS Stack.

Overview

The @8lys/core package provides essential infrastructure for the 8LYS Stack, including:

• Configuration Management: Multi-stage configuration loading, merging, and validation
• Environment Handling: Environment-specific configuration with WordPress Child Theme pattern
• Plugin System: Two-tier plugin architecture with build-time composition
• Validation Engine: ArkType-based validation with custom business rules
• Authentication: Supabase integration with Permit.io permissions

Architecture

Configuration System

The configuration system follows a WordPress Child Theme pattern with the following precedence:

• Environment → Environment-specific overrides (highest priority)
• Product Plugin → Business-specific configurations
• Core Plugin → Platform infrastructure defaults
• Framework → Next.js/React framework defaults (lowest priority)

Two-Tier Plugin Architecture

• Core Plugins (@8lys/* packages): Platform infrastructure
• Product Plugins (plugins/ directory): Business-specific functionality
• Build-Time Composition: Zero runtime overhead, static resolution

Build-Time Plugin Codegen (Static Registry)

The plugin system now uses build-time code generation to produce a static registry that is imported by applications. This eliminates runtime directory scanning and enables optimal tree-shaking.

• Apps run a codegen step before build to emit generated/manifests.ts and generated/registry.ts.
• Consumers use helpers exported from @8lys/core/plugin-system to work with the generated registry:

import { pluginRegistry } from '@generated/registry'
import { listManifests, getManifestById, assertDependenciesSatisfied } from '@8lys/core/plugin-system'

const manifests = listManifests(pluginRegistry)
const auth = getManifestById(pluginRegistry, 'auth')
const deps = assertDependenciesSatisfied(pluginRegistry)

Notes:

• Runtime discovery is not exported in the public API. If you must run discovery during build tooling, import the node-only utility directly inside your build script.

Key Features

Configuration Loading

import { createConfigLoader, loadConfig } from '@8lys/core/config-loader';

// Basic configuration loading
const config = await loadConfig('/config/app.json');

// With validation
const validatedConfig = await loadConfig('/config/app.json', {
  validate: true,
  strict: true
});

Environment-Specific Configuration

import { createEnvironmentHandler } from '@8lys/core/config-loader';

const handler = createEnvironmentHandler({
  environments: ['development', 'staging', 'production'],
  strictValidation: true
});

// Load with automatic environment detection
const result = await handler.loadWithEnvironment('/config/app');

// Load for specific environment
const prodConfig = await handler.loadWithEnvironment('/config/app', 'production');

Configuration Validation

import { validateConfigPipeline, registerValidationRule } from '@8lys/core/config-loader';

// Register custom validation rules
registerValidationRule('api-endpoint', (config) => {
  if (config.api?.url && !config.api.url.startsWith('https://')) {
    return {
      success: false,
      errors: [{ message: 'Production API must use HTTPS' }]
    };
  }
  return { success: true };
});

// Validate configuration
const reports = await validateConfigPipeline(config, 'json', {
  environment: 'production',
  stage: 'post-merge'
});

Environment Variable Resolution

import { resolveEnvironmentVariable } from '@8lys/core/config-loader';

const config = {
  api: { url: '${API_URL}', key: '${API_KEY:default-key}' },
  debug: '\\${NOT_A_VAR}' // Escaped literal
};

const resolved = resolveEnvironmentVariable(config, {
  allowedVariables: ['API_URL', 'API_KEY'],
  validatePatterns: true
});

Configuration File Structure

Base Configuration

{
  "api": {
    "url": "http://localhost:3000",
    "timeout": 5000
  },
  "features": {
    "analytics": false,
    "beta": false
  }
}

Environment-Specific Override

{
  "api": {
    "url": "https://api.production.com"
  },
  "features": {
    "analytics": true
  }
}

Environment Detection

The system automatically detects the current environment from:

• Custom Environment Variable (if specified)
• NODE_ENV environment variable
• Default to 'development' if no environment is set

Supported environments:

• development - Local development
• test - Testing environment
• staging - Pre-production testing
• production - Production environment

Validation Pipeline

The validation system provides multi-stage validation:

• Pre-Merge Validation - Validate individual configuration files
• Post-Merge Validation - Validate merged configuration
• Runtime Validation - Validate configuration during application startup
• Enforcement Validation - Custom business logic validation

Built-in Validation Rules

• Schema Validation: ArkType schema enforcement
• Type Safety: TypeScript type checking
• Required Fields: Ensure required configuration is present
• Format Validation: URL, email, and pattern validation

Plugin Integration

Core Plugin Development

// packages/@8lys/auth/src/index.ts
export interface AuthExtensions {
  readonly customLoginFields?: CustomField[];
  readonly authMiddleware?: AuthMiddleware[];
}

export * from './components/LoginForm';
export * from './hooks/useAuth';
export * from './api/authRouter';

Product Plugin Development

// plugins/inventory-management/manifest.json
{
  "id": "inventory-management",
  "name": "Inventory Management",
  "version": "1.0.0",
  "extends": ["dashboard", "api", "auth"],
  "dependencies": {
    "@8lys/dashboard": "^1.0.0",
    "@8lys/api": "^1.0.0"
  }
}

Testing

The package includes comprehensive test suites following TDD principles:

# Run all tests
pnpm test

# Run specific test suites
pnpm test -- --testNamePattern="Environment Handler"

# Run with coverage
pnpm test -- --coverage

Test Structure

• Unit Tests: Individual function testing
• Integration Tests: Component interaction testing
• End-to-End Tests: Full workflow testing

Development

Prerequisites

• Node.js 18+
• pnpm 8+
• TypeScript 5+

Setup

# Install dependencies
pnpm install

# Build the package
pnpm build

# Run tests
pnpm test

# Run linting
pnpm lint

Architecture Principles

• TypeScript Strict: No any types, strict mode enabled
• Module + Functions: Singleton state as module variables with exported functions
• ESM Hygiene: Named exports, no circular imports
• ArkType Validation: Runtime type validation with ArkType
• Zero Runtime Overhead: Build-time composition for production

Contributing

• Follow the established patterns and architecture
• Write comprehensive tests for new features
• Update documentation for any API changes
• Ensure all tests pass before submitting changes

License

Private - 8LYS Stack internal use only.