{"_id":"@8lys/core","name":"@8lys/core","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@8lys/core","version":"0.1.0","type":"module","description":"Core utilities and types for 8LYS Stack","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"},"./utils":{"import":"./dist/lib/utils.js","types":"./dist/lib/utils.d.ts"},"./plugin-system/codegen":{"import":"./dist/plugin-system/codegen.js","types":"./dist/plugin-system/codegen.d.ts"},"./plugin-system/build-discovery":{"import":"./dist/plugin-system/build-discovery.js","types":"./dist/plugin-system/build-discovery.d.ts"},"./plugin-system/types":{"import":"./dist/plugin-system/types.js","types":"./dist/plugin-system/types.d.ts"}},"dependencies":{"arktype":"^2.1.22","clsx":"^2.1.1","tailwind-merge":"^3.3.1"},"devDependencies":{"@testing-library/jest-dom":"^6.8.0","@vitest/coverage-v8":"^3.2.4","vitest":"^3.2.4"},"peerDependencies":{"react":"^18.0.0","react-dom":"^18.0.0"},"scripts":{"build":"tsc && cp -r templates dist/","dev":"tsc --watch","test":"vitest","test:watch":"vitest --watch","test:ui":"vitest --ui","test:coverage":"vitest --coverage","test:ci":"vitest run --reporter=dot","lint":"../../node_modules/.bin/eslint src --ext .ts,.tsx","clean":"rm -rf dist"},"_id":"@8lys/core@0.1.0","_integrity":"sha512-EQ2ripbOnjH2n0/5KBaHXuXrnEDf8Skr1yc5NAwGvY/7fjdQByTl+HxwrNnLouO/fqjGdtObz8CPXpwGODDGPA==","_resolved":"/private/var/folders/92/ygpbf5k95cx_y7tsg6pq2jxm0000gp/T/f8ab9aee087a38cebefd455b541526cb/8lys-core-0.1.0.tgz","_from":"file:8lys-core-0.1.0.tgz","_nodeVersion":"24.1.0","_npmVersion":"11.3.0","dist":{"integrity":"sha512-EQ2ripbOnjH2n0/5KBaHXuXrnEDf8Skr1yc5NAwGvY/7fjdQByTl+HxwrNnLouO/fqjGdtObz8CPXpwGODDGPA==","shasum":"2d96e4a6bcba06af45923a367fd7745b64bf8eee","tarball":"https://registry.npmjs.org/@8lys/core/-/core-0.1.0.tgz","fileCount":108,"unpackedSize":479046,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCd8MfV6w1gGNeSCjaQl4uc9/c5pCLWrVmrh12GxDtc8gIgNgI0gx0dTAm/7qTHdt9tV+nSUXsLlDQuhLsFlzcyLJc="}]},"_npmUser":{"name":"8lys","email":"npm@8lys.mx"},"directories":{},"maintainers":[{"name":"8lys","email":"npm@8lys.mx"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/core_0.1.0_1758010018463_0.9113873775733641"},"_hasShrinkwrap":false}},"time":{"created":"2025-09-16T08:06:58.396Z","0.1.0":"2025-09-16T08:06:58.638Z","modified":"2025-09-16T08:06:58.944Z"},"maintainers":[{"name":"8lys","email":"npm@8lys.mx"}],"description":"Core utilities and types for 8LYS Stack","readme":"# @8lys/core\n\nCore utilities and configuration management for the 8LYS Stack.\n\n## Overview\n\nThe `@8lys/core` package provides essential infrastructure for the 8LYS Stack, including:\n\n- **Configuration Management**: Multi-stage configuration loading, merging, and validation\n- **Environment Handling**: Environment-specific configuration with WordPress Child Theme pattern\n- **Plugin System**: Two-tier plugin architecture with build-time composition\n- **Validation Engine**: ArkType-based validation with custom business rules\n- **Authentication**: Supabase integration with Permit.io permissions\n\n## Architecture\n\n### Configuration System\n\nThe configuration system follows a **WordPress Child Theme pattern** with the following precedence:\n\n1. **Environment** → Environment-specific overrides (highest priority)\n2. **Product Plugin** → Business-specific configurations\n3. **Core Plugin** → Platform infrastructure defaults\n4. **Framework** → Next.js/React framework defaults (lowest priority)\n\n### Two-Tier Plugin Architecture\n\n- **Core Plugins** (`@8lys/*` packages): Platform infrastructure\n- **Product Plugins** (`plugins/` directory): Business-specific functionality\n- **Build-Time Composition**: Zero runtime overhead, static resolution\n\n#### Build-Time Plugin Codegen (Static Registry)\n\nThe 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.\n\n- Apps run a codegen step before build to emit `generated/manifests.ts` and `generated/registry.ts`.\n- Consumers use helpers exported from `@8lys/core/plugin-system` to work with the generated registry:\n\n```ts\nimport { pluginRegistry } from '@generated/registry'\nimport { listManifests, getManifestById, assertDependenciesSatisfied } from '@8lys/core/plugin-system'\n\nconst manifests = listManifests(pluginRegistry)\nconst auth = getManifestById(pluginRegistry, 'auth')\nconst deps = assertDependenciesSatisfied(pluginRegistry)\n```\n\nNotes:\n- 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.\n\n## Key Features\n\n### Configuration Loading\n\n```typescript\nimport { createConfigLoader, loadConfig } from '@8lys/core/config-loader';\n\n// Basic configuration loading\nconst config = await loadConfig('/config/app.json');\n\n// With validation\nconst validatedConfig = await loadConfig('/config/app.json', {\n  validate: true,\n  strict: true\n});\n```\n\n### Environment-Specific Configuration\n\n```typescript\nimport { createEnvironmentHandler } from '@8lys/core/config-loader';\n\nconst handler = createEnvironmentHandler({\n  environments: ['development', 'staging', 'production'],\n  strictValidation: true\n});\n\n// Load with automatic environment detection\nconst result = await handler.loadWithEnvironment('/config/app');\n\n// Load for specific environment\nconst prodConfig = await handler.loadWithEnvironment('/config/app', 'production');\n```\n\n### Configuration Validation\n\n```typescript\nimport { validateConfigPipeline, registerValidationRule } from '@8lys/core/config-loader';\n\n// Register custom validation rules\nregisterValidationRule('api-endpoint', (config) => {\n  if (config.api?.url && !config.api.url.startsWith('https://')) {\n    return {\n      success: false,\n      errors: [{ message: 'Production API must use HTTPS' }]\n    };\n  }\n  return { success: true };\n});\n\n// Validate configuration\nconst reports = await validateConfigPipeline(config, 'json', {\n  environment: 'production',\n  stage: 'post-merge'\n});\n```\n\n### Environment Variable Resolution\n\n```typescript\nimport { resolveEnvironmentVariable } from '@8lys/core/config-loader';\n\nconst config = {\n  api: { url: '${API_URL}', key: '${API_KEY:default-key}' },\n  debug: '\\\\${NOT_A_VAR}' // Escaped literal\n};\n\nconst resolved = resolveEnvironmentVariable(config, {\n  allowedVariables: ['API_URL', 'API_KEY'],\n  validatePatterns: true\n});\n```\n\n## Configuration File Structure\n\n### Base Configuration\n\n```json\n{\n  \"api\": {\n    \"url\": \"http://localhost:3000\",\n    \"timeout\": 5000\n  },\n  \"features\": {\n    \"analytics\": false,\n    \"beta\": false\n  }\n}\n```\n\n### Environment-Specific Override\n\n```json\n{\n  \"api\": {\n    \"url\": \"https://api.production.com\"\n  },\n  \"features\": {\n    \"analytics\": true\n  }\n}\n```\n\n## Environment Detection\n\nThe system automatically detects the current environment from:\n\n1. **Custom Environment Variable** (if specified)\n2. **NODE_ENV** environment variable\n3. **Default to 'development'** if no environment is set\n\nSupported environments:\n- `development` - Local development\n- `test` - Testing environment\n- `staging` - Pre-production testing\n- `production` - Production environment\n\n## Validation Pipeline\n\nThe validation system provides multi-stage validation:\n\n1. **Pre-Merge Validation** - Validate individual configuration files\n2. **Post-Merge Validation** - Validate merged configuration\n3. **Runtime Validation** - Validate configuration during application startup\n4. **Enforcement Validation** - Custom business logic validation\n\n### Built-in Validation Rules\n\n- **Schema Validation**: ArkType schema enforcement\n- **Type Safety**: TypeScript type checking\n- **Required Fields**: Ensure required configuration is present\n- **Format Validation**: URL, email, and pattern validation\n\n## Plugin Integration\n\n### Core Plugin Development\n\n```typescript\n// packages/@8lys/auth/src/index.ts\nexport interface AuthExtensions {\n  readonly customLoginFields?: CustomField[];\n  readonly authMiddleware?: AuthMiddleware[];\n}\n\nexport * from './components/LoginForm';\nexport * from './hooks/useAuth';\nexport * from './api/authRouter';\n```\n\n### Product Plugin Development\n\n```typescript\n// plugins/inventory-management/manifest.json\n{\n  \"id\": \"inventory-management\",\n  \"name\": \"Inventory Management\",\n  \"version\": \"1.0.0\",\n  \"extends\": [\"dashboard\", \"api\", \"auth\"],\n  \"dependencies\": {\n    \"@8lys/dashboard\": \"^1.0.0\",\n    \"@8lys/api\": \"^1.0.0\"\n  }\n}\n```\n\n## Testing\n\nThe package includes comprehensive test suites following TDD principles:\n\n```bash\n# Run all tests\npnpm test\n\n# Run specific test suites\npnpm test -- --testNamePattern=\"Environment Handler\"\n\n# Run with coverage\npnpm test -- --coverage\n```\n\n### Test Structure\n\n- **Unit Tests**: Individual function testing\n- **Integration Tests**: Component interaction testing\n- **End-to-End Tests**: Full workflow testing\n\n## Development\n\n### Prerequisites\n\n- Node.js 18+\n- pnpm 8+\n- TypeScript 5+\n\n### Setup\n\n```bash\n# Install dependencies\npnpm install\n\n# Build the package\npnpm build\n\n# Run tests\npnpm test\n\n# Run linting\npnpm lint\n```\n\n### Architecture Principles\n\n1. **TypeScript Strict**: No `any` types, strict mode enabled\n2. **Module + Functions**: Singleton state as module variables with exported functions\n3. **ESM Hygiene**: Named exports, no circular imports\n4. **ArkType Validation**: Runtime type validation with ArkType\n5. **Zero Runtime Overhead**: Build-time composition for production\n\n## Contributing\n\n1. Follow the established patterns and architecture\n2. Write comprehensive tests for new features\n3. Update documentation for any API changes\n4. Ensure all tests pass before submitting changes\n\n## License\n\nPrivate - 8LYS Stack internal use only. ","readmeFilename":"README.md","_rev":"1-16f37699770f8f943be6803c29698d0a"}