metabuilder/seed

Seed - Package System Bootstrap

This directory contains seed data and configuration for bootstrapping the MetaBuilder package system.

Directory Structure

seed/
├── packages/           # Package installation manifests
│   └── core-packages.yaml
├── database/          # Database seed data (DBAL format)
│   ├── installed_packages.yaml
│   └── package_permissions.yaml
├── config/            # System configuration
│   ├── bootstrap.yaml
│   └── package-repo.yaml
└── README.md

Purpose

The seed system provides:

1. Core Package Definitions - Which packages to auto-install on first boot
2. Database Seeds - Initial records for InstalledPackage and PackagePermission tables
3. Bootstrap Configuration - How the package system initializes
4. Repository Configuration - Where packages are loaded from and how conflicts are resolved

Files

packages/core-packages.yaml

Defines the packages that should be automatically installed during system bootstrap.

Categories:

• packages - Core required packages (package_manager, ui components, dashboard, etc.)
• recommended - Optional but recommended packages (notifications, audit log, etc.)
• development - Dev-only tools (testing framework, validators, editors)

Fields:

• packageId - Unique package identifier (snake_case)
• version - Semantic version (e.g., "1.0.0")
• enabled - Whether package is active by default
• priority - Installation order (lower = earlier)
• required - Whether bootstrap fails if this package can't be installed

Bootstrap Phases:

1. Core System (package_manager)
2. Base UI (header, footer, auth, login)
3. Essential Features (dashboard)
4. Administration (user_manager, role_editor)
5. Admin Tools (database_manager, schema_editor)
6. Recommended Packages (optional)

database/installed_packages.yaml

Seed data for the InstalledPackage table matching the Prisma schema at prisma/schema.prisma:327.

Fields:

• packageId - Unique identifier (primary key)
• tenantId - Tenant isolation (null = system-wide)
• installedAt - Timestamp (0 = use current time)
• version - Package version
• enabled - Whether package is active
• config - JSON configuration specific to each package

Special Flags:

• systemPackage: true - Core packages that cannot be uninstalled
• uninstallProtection: true - Prevents accidental removal
• minLevel - Minimum permission level to access (1-5)
• dangerousOperations: true - Packages that can modify system

database/package_permissions.yaml

Seed data for the PackagePermission table matching prisma/schema.prisma:1637.

Permission Levels (MetaBuilder 6-level system):

• 0: public - Unauthenticated users
• 1: user - Authenticated users
• 2: moderator - Content moderators
• 3: admin - Tenant administrators
• 4: god - System administrators
• 5: supergod - Super administrators

Permission Types:

• read - View/access package features
• write - Modify package data
• execute - Execute package scripts
• admin - Full package administration

Default Permissions:

• UI packages (header, footer, login) → public or user level
• Dashboard → user level
• User management → admin level
• Package management → god level
• Database/schema tools → supergod only

config/bootstrap.yaml

Controls how the package system initializes.

Key Sections:

bootstrap:

• mode - auto | manual | interactive
• failOnError - Continue if optional packages fail
• validatePackages - Verify package.json before installing
• skipBrokenPackages - Skip invalid packages

phases: Defines installation phases that map to core-packages.yaml priorities.

database:

• seedFiles - YAML files to load into database
• skipIfPopulated - Don't re-seed existing data
• useTransactions - Rollback on failure

hooks: DBAL CLI commands to run at various stages:

• preBootstrap - Before any operations
• postBootstrap - After successful completion
• onError - If bootstrap fails
• prePhase/postPhase - Around each installation phase

Environment Overrides:

• development - Verbose logging, include dev tools
• production - Fail on errors, exclude dev tools
• test - Always re-seed, use transactions

config/package-repo.yaml

Package repository configuration.

Key Sections:

sources: Where to load packages from (priority order):

• local - /packages directory (priority 0)
• Future: remote registries, git repositories

discovery:

• scanPatterns - Glob patterns to find packages
• excludePatterns - Directories to ignore
• maxConcurrent - Parallel discovery limit

validation:

• requiredFields - Must be present in package.json
• schemaUrl - JSON schema for validation
• packageIdPattern - Regex for valid IDs (snake_case)

dependencies:

• missingDependencies - error | warn | ignore
• detectCircular - Find circular dependency chains

conflicts:

• strategy: priority - Use lowest-priority source
• duplicateVersions: newest - Pick latest version

security:

• sandboxPackageScripts - Isolate package code
• disallowedPatterns - Prevent dangerous code

Usage

Bootstrap with DBAL CLI

# Run bootstrap process
dbal bootstrap --config seed/config/bootstrap.yaml

# Dry run (simulate without changes)
dbal bootstrap --dry-run

# Interactive mode
dbal bootstrap --interactive

# Specific environment
dbal bootstrap --env production

Seed Database Only

# Seed all database files
dbal seed --dir seed/database

# Seed specific file
dbal seed seed/database/installed_packages.yaml

# Force re-seed (ignore skipIfExists)
dbal seed --force

Validate Configuration

# Validate all seed files
dbal validate --dir seed

# Validate package definitions
dbal validate seed/packages/core-packages.yaml

# Check database seeds against schema
dbal validate-schema seed/database/*.yaml

Install Specific Packages

# Install core packages only
dbal install-packages --manifest seed/packages/core-packages.yaml --filter priority=1-3

# Install recommended packages
dbal install-packages --manifest seed/packages/core-packages.yaml --filter section=recommended

# Install development tools
dbal install-packages --manifest seed/packages/core-packages.yaml --filter section=development

Bootstrap Process Flow

1. Pre-bootstrap hooks - Run preparation commands
2. Validate configuration - Check seed files and package definitions
3. Phase 1: Core System
   • Install package_manager
   • Seed database records
   • Verify installation
4. Phase 2: Base UI
   • Install ui_header, ui_footer, ui_auth, ui_login
   • Set up permissions
5. Phase 3-5: Features & Admin
   • Install dashboard, user management, admin tools
6. Phase 6: Recommended (optional)
   • Install notification_center, audit_log, etc.
7. Phase 7: Development (dev only)
   • Install testing, validators, editors
8. Post-bootstrap hooks - Verification and cleanup
9. Logging - Record installation to logs/bootstrap.log

Integration with Existing System

Frontend Integration

The bootstrap system integrates with:

• frontends/nextjs/src/lib/db/packages - Package CRUD operations
• frontends/nextjs/src/lib/packages - Package loading and discovery

DBAL Integration

Seed files use DBAL entity schemas:

• dbal/shared/api/schema/entities/core/package.yaml
• Package CRUD operations in dbal/development/src/core/entities/package

Database Schema

Seed data matches Prisma schema:

• prisma/schema.prisma:327 - InstalledPackage model
• prisma/schema.prisma:1637 - PackagePermission model

Customization

Adding Custom Packages to Bootstrap

1. Edit seed/packages/core-packages.yaml:

packages:
  - packageId: my_custom_package
    version: "1.0.0"
    enabled: true
    priority: 10
    required: false
    description: "My custom functionality"

2. Add database seed in seed/database/installed_packages.yaml:

records:
  - packageId: my_custom_package
    tenantId: null
    installedAt: 0
    version: "1.0.0"
    enabled: true
    config: |
      {
        "customSetting": "value"
      }

3. Add permissions in seed/database/package_permissions.yaml:

records:
  - id: perm_my_custom_user_read
    packageId: my_custom_package
    role: user
    permission: read
    granted: true

Environment-Specific Bootstrapping

Modify seed/config/bootstrap.yaml:

environments:
  staging:
    bootstrap:
      verbose: true
      failOnError: false
    phases:
      - id: 7
        enabled: true  # Include dev tools in staging

Custom Package Sources

Edit seed/config/package-repo.yaml:

sources:
  - id: company-packages
    name: "Company Private Packages"
    type: git
    url: https://github.com/company/metabuilder-packages.git
    priority: 5
    enabled: true

Troubleshooting

Bootstrap Fails

Check logs:

cat logs/bootstrap.log

Common issues:

• Missing package directories → Verify /packages exists
• Database connection → Check DBAL daemon is running
• Permission denied → Ensure user has supergod role
• Version conflicts → Check package versions in core-packages.yaml

Package Not Installing

# Validate package
dbal validate packages/my_package/package.json

# Check for errors
dbal install-package my_package --verbose

# Verify dependencies
dbal check-dependencies my_package

Re-running Bootstrap

Bootstrap is idempotent with skipIfPopulated: true. To force re-bootstrap:

# Clear package data
dbal seed --force seed/database/installed_packages.yaml

# Re-run bootstrap
dbal bootstrap --force

Future Enhancements

• Remote package registry support
• Package signing and verification
• Automatic dependency resolution
• Package update notifications
• Rollback capabilities
• Multi-environment sync
• Package health checks
• Usage analytics

See Also

• Main README - Project overview
• Package System Documentation - Package architecture
• DBAL Documentation - Database layer
• Package Schema Examples - Package examples
• 6-Level Permission System - Access control

---

Generated with Claude Code