@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:

1. Environment → Environment-specific overrides (highest priority)
2. Product Plugin → Business-specific configurations
3. Core Plugin → Platform infrastructure defaults
4. 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:

1. Custom Environment Variable (if specified)
2. NODE_ENV environment variable
3. 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:

1. Pre-Merge Validation - Validate individual configuration files
2. Post-Merge Validation - Validate merged configuration
3. Runtime Validation - Validate configuration during application startup
4. 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

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

Contributing

1. Follow the established patterns and architecture
2. Write comprehensive tests for new features
3. Update documentation for any API changes
4. Ensure all tests pass before submitting changes

License

Private - 8LYS Stack internal use only.