Implement core hypervisor services and systemd generators

.claude/agents/systemd-config-expert.md

@@ -8,70 +8,26 @@ You are a systemd configuration expert with comprehensive knowledge of the syste
 
 **Core Competencies:**
 
-You possess deep understanding of:
-- All systemd unit types: services, sockets, timers, mounts, automounts, paths, slices, scopes, targets, and devices
-- Systemd syntax rules including section headers, directives, specifiers, and escape sequences
-- Custom systemd generators and their execution environment
-- Boot process orchestration and dependency management
-- Root filesystem discovery and Discoverable Partitions Specification (DPS)
-- Portable services and system/configuration extensions (sysext/confext)
-- Container integration with systemd-nspawn and systemd-vmspawn
-- Network configuration with systemd-networkd
-- Resource control and cgroup management
+You possess deep understanding of: - All systemd unit types: services, sockets, timers, mounts, automounts, paths, slices, scopes, targets, and devices - Systemd syntax rules including section headers, directives, specifiers, and escape sequences - Custom systemd generators and their execution environment - Boot process orchestration and dependency management - Root filesystem discovery and Discoverable Partitions Specification (DPS) - Portable services and system/configuration extensions (sysext/confext) - Container integration with systemd-nspawn and systemd-vmspawn - Network configuration with systemd-networkd - Resource control and cgroup management
 
 **Configuration Generation Guidelines:**
 
-When creating systemd configurations, you will:
-1. Always produce syntactically valid systemd unit files following the exact specification
-2. Use appropriate section headers ([Unit], [Service], [Install], etc.) with correct capitalization
-3. Apply proper directive naming conventions (PascalCase for most directives)
-4. Include essential directives like Description=, After=, Wants=, Type=, ExecStart=
-5. Implement proper dependency ordering and conflict resolution
-6. Use systemd specifiers (%i, %n, %u, etc.) appropriately for templated units
-7. Apply security best practices: PrivateTmp=, ProtectSystem=, NoNewPrivileges=, etc.
-8. Configure resource limits appropriately with Limit* directives
-9. Set up proper logging with StandardOutput= and StandardError=
-10. Implement restart policies and failure handling
+When creating systemd configurations, you will: 1. Always produce syntactically valid systemd unit files following the exact specification 2. Use appropriate section headers (\[Unit\], \[Service\], \[Install\], etc.) with correct capitalization 3. Apply proper directive naming conventions (PascalCase for most directives) 4. Include essential directives like Description=, After=, Wants=, Type=, ExecStart= 5. Implement proper dependency ordering and conflict resolution 6. Use systemd specifiers (%i, %n, %u, etc.) appropriately for templated units 7. Apply security best practices: PrivateTmp=, ProtectSystem=, NoNewPrivileges=, etc. 8. Configure resource limits appropriately with Limit\* directives 9. Set up proper logging with StandardOutput= and StandardError= 10. Implement restart policies and failure handling
 
 **Generator Development Principles:**
 
-For systemd generators, you will:
-1. Write generators that execute in the limited early-boot environment
-2. Output generated units to the correct directories ($1, $2, $3 arguments)
-3. Avoid side effects and ensure idempotent execution
-4. Parse configuration from /etc/, /run/, and /usr/lib/ in proper precedence
-5. Generate .wants/ and .requires/ symlinks for dependencies
-6. Handle error conditions gracefully without blocking boot
-7. Follow the generator naming convention and installation paths
+For systemd generators, you will: 1. Write generators that execute in the limited early-boot environment 2. Output generated units to the correct directories (\$1, \$2, \$3 arguments) 3. Avoid side effects and ensure idempotent execution 4. Parse configuration from /etc/, /run/, and /usr/lib/ in proper precedence 5. Generate .wants/ and .requires/ symlinks for dependencies 6. Handle error conditions gracefully without blocking boot 7. Follow the generator naming convention and installation paths
 
 **ROOTFS_DISCOVERY Expertise:**
 
-You will implement discoverable root filesystems by:
-1. Following GPT partition type GUIDs for automatic discovery
-2. Implementing proper /etc/fstab alternatives through DPS
-3. Configuring systemd-gpt-auto-generator behavior
-4. Setting up dm-verity for verified boot scenarios
-5. Implementing A/B root partition schemes
-6. Handling LUKS encrypted root filesystems
-7. Configuring systemd-repart for automatic partitioning
+You will implement discoverable root filesystems by: 1. Following GPT partition type GUIDs for automatic discovery 2. Implementing proper /etc/fstab alternatives through DPS 3. Configuring systemd-gpt-auto-generator behavior 4. Setting up dm-verity for verified boot scenarios 5. Implementing A/B root partition schemes 6. Handling LUKS encrypted root filesystems 7. Configuring systemd-repart for automatic partitioning
 
 **Quality Assurance:**
 
-Before providing any configuration, you will:
-1. Validate syntax against systemd.syntax specifications
-2. Check for common pitfalls (missing Install section, circular dependencies)
-3. Ensure compatibility with the target systemd version
-4. Verify security implications of the configuration
-5. Test for proper escaping of special characters
-6. Confirm correct file permissions and ownership requirements
+Before providing any configuration, you will: 1. Validate syntax against systemd.syntax specifications 2. Check for common pitfalls (missing Install section, circular dependencies) 3. Ensure compatibility with the target systemd version 4. Verify security implications of the configuration 5. Test for proper escaping of special characters 6. Confirm correct file permissions and ownership requirements
 
 **Output Format:**
 
-You will provide configurations in ready-to-use format with:
-- Clear file naming following systemd conventions (unit-name.service, generator-name, etc.)
-- Installation instructions including target directories
-- Enablement and activation commands
-- Testing and debugging guidance using journalctl and systemctl
-- Explanation of key directives and their purposes
+You will provide configurations in ready-to-use format with: - Clear file naming following systemd conventions (unit-name.service, generator-name, etc.) - Installation instructions including target directories - Enablement and activation commands - Testing and debugging guidance using journalctl and systemctl - Explanation of key directives and their purposes
 
 When asked about systemd topics, provide authoritative answers based on official systemd documentation. Always prioritize correctness and security in your configurations. If a request involves deprecated features, suggest modern alternatives while explaining the migration path.

.github/copilot-instructions.md

@@ -7,18 +7,21 @@ BitBuilder Hypervisor is a revolutionary git-ops-native, multi-tenant hypervisor
 ## Core Architecture Paradigms
 
 ### 1. Immutable Infrastructure
+
 - Host OS is completely immutable after boot - no runtime modifications allowed
 - All changes applied through layered overlays (sysext/confext)
 - Configuration drift eliminated by design
 - Rollback capability built-in through Git history and A/B boot partitions
 
 ### 2. Git-Ops Native Design
+
 - **Git is the single source of truth** for all configuration
 - Each tenant has its own dedicated Git repository
 - System pulls configuration changes at boot time via `systemd-import-generator`
 - All infrastructure changes must go through Git commits
 
 ### 3. systemd-Native Architecture
+
 - Built entirely on systemd ecosystem: `systemd-vmspawn`, `systemd-nspawn`, `systemd-networkd`, `systemd-homed`
 - Custom systemd generators for dynamic tenant discovery and unit creation
 - Template-based service instantiation using `@` parameterization
@@ -27,13 +30,13 @@ BitBuilder Hypervisor is a revolutionary git-ops-native, multi-tenant hypervisor
 ## Key Technical Patterns
 
 ### systemd Generators
-Custom generators in `/usr/lib/systemd/system-generators/`:
-- `tenant-generator` - Discovers tenants and generates service units
-- `mount-generator` - Creates overlay mounts for extensions
-- Generate units dynamically based on tenant configurations
+
+Custom generators in `/usr/lib/systemd/system-generators/`: - `tenant-generator` - Discovers tenants and generates service units - `mount-generator` - Creates overlay mounts for extensions - Generate units dynamically based on tenant configurations
 
 ### Template Repository Structure
+
 Each tenant template follows strict filesystem hierarchy:
+
 ```
 tenant-<name>/
 ├── metadata.json                 # Tenant metadata (required)
@@ -49,40 +52,40 @@ tenant-<name>/
 ```
 
 ### Extension Image Rules
+
 - **sysext**: Only `/usr/` and `/opt/` directories allowed
 - **confext**: Only `/etc/` directory allowed
 - Must include `extension-release.d/extension-release.<name>` files
 - Images created with `mksquashfs` or similar
 
 ### Linux Userspace API Compliance
-Strict adherence to [UAPI specifications](https://uapi-group.org/specifications/):
-- **Discoverable Partitions Specification (DPS)** for partition layout
-- **Discoverable Disk Image (DDI)** for system images
-- **Unified Kernel Image (UKI)** for secure boot
-- **Boot Loader Specification (BLS)** for boot configuration
-- **Configuration Files Specification** for `/etc`, `/usr/lib`, `/run` hierarchy
+
+Strict adherence to [UAPI specifications][]: - **Discoverable Partitions Specification (DPS)** for partition layout - **Discoverable Disk Image (DDI)** for system images - **Unified Kernel Image (UKI)** for secure boot - **Boot Loader Specification (BLS)** for boot configuration - **Configuration Files Specification** for `/etc`, `/usr/lib`, `/run` hierarchy
 
 ## Critical Workflows
 
 ### Tenant Provisioning Flow
-1. Create tenant Git repository with `metadata.json`
-2. systemd generators discover new tenant (boot-time or timer-based)
-3. Clone tenant repository to `/var/lib/tenants/<id>/config.git/`
-4. Generate systemd units: `tenant@<id>.service`, `tenant-infra@<id>.service`, etc.
-5. Create network namespace and apply configurations
-6. Mount extension overlays (sysext/confext)
-7. Launch `systemd-vmspawn` or `systemd-nspawn` instance
-8. Execute provisioning scripts
+
+1.  Create tenant Git repository with `metadata.json`
+2.  systemd generators discover new tenant (boot-time or timer-based)
+3.  Clone tenant repository to `/var/lib/tenants/<id>/config.git/`
+4.  Generate systemd units: `tenant@<id>.service`, `tenant-infra@<id>.service`, etc.
+5.  Create network namespace and apply configurations
+6.  Mount extension overlays (sysext/confext)
+7.  Launch `systemd-vmspawn` or `systemd-nspawn` instance
+8.  Execute provisioning scripts
 
 ### Boot Process Sequence
-1. **UEFI** → `systemd-boot` loads UKI (Unified Kernel Image)
-2. **systemd-import-generator** downloads/verifies DDI (Discoverable Disk Image)
-3. **Immutable host OS** starts with minimal services
-4. **Git sync service** pulls system-level configurations
-5. **Tenant discovery** via systemd generators scanning Git repositories
-6. **Tenant provisioning** for each discovered tenant
+
+1.  **UEFI** → `systemd-boot` loads UKI (Unified Kernel Image)
+2.  **systemd-import-generator** downloads/verifies DDI (Discoverable Disk Image)
+3.  **Immutable host OS** starts with minimal services
+4.  **Git sync service** pulls system-level configurations
+5.  **Tenant discovery** via systemd generators scanning Git repositories
+6.  **Tenant provisioning** for each discovered tenant
 
 ### Configuration Management
+
 - All configurations declarative in YAML/JSON formats
 - Tenant metadata follows specific JSON schema (see `STACK.md`)
 - systemd unit files use extensive templating with `%i` substitution
@@ -91,44 +94,47 @@ Strict adherence to [UAPI specifications](https://uapi-group.org/specifications/
 ## Development Conventions
 
 ### File Hierarchy Standards
+
 - Follow Linux Filesystem Hierarchy Specification precisely
 - Templates must include `/etc/os-release` and `/usr/lib/os-release` symlink
 - Extension images require proper `extension-release` metadata
 - Validate filesystem compliance with provided validation scripts
 
 ### systemd Unit Patterns
+
 - Use template units with `@` for parameterization: `tenant@.service`
 - Dependency management with `After=`, `Wants=`, `BindsTo=`
 - Resource isolation via `PrivateTmp=`, `ProtectSystem=`, `PrivateUsers=`
 - Network isolation through `PrivateNetwork=` and custom bridges
 
 ### Git Repository Organization
+
 - System repository: Global configurations, generators, templates
 - Tenant repositories: Individual tenant configurations
 - Template repositories: Reusable tenant templates
 - All repositories follow `.gitops/config.yaml` conventions
 
 ### Security Boundaries
-Multiple isolation layers per tenant:
-- **Hardware**: VT-x/AMD-V virtualization, UEFI Secure Boot
-- **Kernel**: Namespace isolation (PID, NET, MNT, UTS, IPC, USER)
-- **systemd**: Capability dropping, seccomp filters, SELinux contexts
-- **Network**: Dedicated bridges, VLANs, VPNs per tenant
+
+Multiple isolation layers per tenant: - **Hardware**: VT-x/AMD-V virtualization, UEFI Secure Boot - **Kernel**: Namespace isolation (PID, NET, MNT, UTS, IPC, USER) - **systemd**: Capability dropping, seccomp filters, SELinux contexts - **Network**: Dedicated bridges, VLANs, VPNs per tenant
 
 ## Key Files and Directories
 
 ### Documentation (Critical Reading)
+
 - `README.md` - Main architecture overview
 - `STACK.md` - Template system and implementation details
 - `specs/ARCHITECTURE.md` - System architecture and design decisions
 - `specs/DESIGN.md` - Technical implementation details
 
 ### Template Structure
+
 - `packages/templates/` - Template repository definitions (currently empty)
 - `/usr/lib/bitbuilder/templates/` - System-wide templates (runtime)
 - `/var/lib/tenants/<id>/` - Per-tenant runtime data
 
 ### Configuration Locations
+
 - `/etc/systemd/system/` - systemd unit templates
 - `/usr/lib/systemd/system-generators/` - Custom generators
 - `/usr/lib/extensions/` - System-wide extension images
@@ -137,21 +143,26 @@ Multiple isolation layers per tenant:
 ## Development Guidelines
 
 ### When Working with Templates
+
 - Always validate filesystem hierarchy compliance
 - Include proper `metadata.json` with schema validation
 - Test extension image mounting and overlay functionality
 - Verify systemd unit generation and dependency resolution
 
 ### When Implementing systemd Integration
+
 - Use systemd's native capabilities rather than external tools
 - Implement proper service dependencies and ordering
 - Follow systemd unit file best practices for security
 - Test generator scripts thoroughly with various configurations
 
 ### When Documenting Architecture
+
 - Maintain consistency with existing architectural patterns
 - Update relevant specification documents when making changes
 - Include implementation examples from actual configurations
 - Reference UAPI specifications for compliance requirements
 
 This project represents a paradigm shift toward declarative, immutable infrastructure management through Git-Ops and systemd's advanced virtualization capabilities.
+
+[UAPI specifications]: https://uapi-group.org/specifications/

.gitignore

@@ -17,3 +17,11 @@ CMakeUserPresets.json
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #cmake-build-*
+
+# Node.js dependencies
+node_modules/
+package-lock.json
+
+# Build outputs
+dist/
+*.log

.gitmodules

@@ -4,3 +4,6 @@
 [submodule "docs/systemd/systemd"]
 	path = docs/systemd/systemd
 	url = https://github.com/systemd/systemd
+[submodule "infra/bbos"]
+	path = infra/bbos
+	url = https://github.com/bitbuilder-io/bbos

.oxlintrc.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "rules": {
+    "typescript": "error",
+    "suspicious": "error",
+    "correctness": "error",
+    "style": "error",
+    "pedantic": "warn"
+  },
+  "import-plugin": true,
+  "jsdoc-plugin": true
+}

.prettierignore

@@ -0,0 +1,30 @@
+# Dependencies
+node_modules/
+package-lock.json
+bun.lock
+
+# Build outputs
+dist/
+*.log
+
+# Git
+.git/
+.gitignore
+.gitmodules
+
+# Config files that prettier can't parse
+.oxlintrc.json
+
+# Binary and non-text files
+*.png
+*.jpg
+*.jpeg
+*.gif
+*.ico
+*.pdf
+*.zip
+*.tar.gz
+
+# Other configs
+LICENSE
+*.list

.prettierrc.yml

@@ -0,0 +1,12 @@
+semi: true
+singleQuote: true
+trailingComma: es5
+printWidth: 80
+tabWidth: 2
+proseWrap: preserve
+overrides:
+  - files: '*.ts'
+    options:
+      parser: typescript
+      plugins:
+        - '@prettier/plugin-oxc'