General: Version bumped to v0.0.92

.github/workflows/ci.yml

@@ -0,0 +1,61 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, dev, stable ]
+  pull_request:
+    branches: [ main, dev, stable ]
+
+jobs:
+  syntax:
+    name: PHP Syntax Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.2'
+          coverage: none
+          extensions: pdo_sqlite,sqlite3
+      - name: Install dependencies
+        run: composer install --no-interaction
+      - name: PHP lint all PHP files
+        run: |
+          find . -name '*.php' -not -path './vendor/*' -not -path './.phpunit.result.cache' | xargs -I{} php -l {} 2>&1 | grep -v 'No syntax errors' | head -20 || true
+
+  tests:
+    name: PHPUnit Tests
+    runs-on: ubuntu-latest
+    needs: syntax
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.2'
+          coverage: none
+          extensions: pdo_sqlite,sqlite3
+      - name: Clear test environment
+        run: |
+          rm -rf /tmp/*sqlite* || true
+          mkdir -p /tmp/test-db
+          chmod 777 /tmp/test-db
+      - name: Install dependencies
+        run: composer install --no-interaction
+      - name: Run PHPUnit
+        run: vendor/bin/phpunit tests/ --testdox
+
+  coding-style:
+    name: Coding Style
+    runs-on: ubuntu-latest
+    needs: syntax
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.2'
+      - name: Check PSR-12 compliance
+        run: |
+          git diff --check HEAD~1 2>/dev/null || true

.github/workflows/release.yml

@@ -6,6 +6,24 @@ on:
       - 'v*'
 
 jobs:
+  ci:
+    name: CI Pre-check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.2'
+          coverage: none
+      - name: Install dependencies
+        run: composer install --no-interaction
+      - name: PHP syntax check
+        run: |
+          find . -name '*.php' -not -path './vendor/*' -not -path './.phpunit.result.cache' -not -path './lib/themes/*' -print0 | xargs -0 -I{} php -l {} 2>&1 | grep -v 'No syntax errors' | head -20 || true
+      - name: Run PHPUnit
+        run: vendor/bin/phpunit tests/ --testdox
+
   release:
     runs-on: ubuntu-latest
     steps:

.gitignore

@@ -16,6 +16,7 @@ TOKEN
 /Definition/
 
 # lib: exclude only .sh in lib root and the skeleton dir
+/lib
 /lib/                  # ignore everything in /lib
 /lib/**                #  ...and everything inside it
 !/lib/*.sh             # keep .sh files directly in /lib
@@ -50,6 +51,10 @@ TOKEN
 # Backups
 /backup/
 
+# PHPUnit
+.phpunit.result.cache
+*.cache
+
 # Example Files
 /example/vendor/
 
@@ -60,3 +65,6 @@ TOKEN
 # composer.lock
 .venv
 rag_index.json
+
+# Debug scripts
+debug_*.php

.opencode/opencode.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "instructions": [
+    "AGENTS.md",
+    "ROADMAP.md",
+    "DESIGN.md"
+  ],
+  "permission": {
+    "edit": "allow",
+    "write": "allow",
+    "bash": {
+      "*": "ask",
+      "git status*": "allow",
+      "git diff*": "allow",
+      "git add*": "allow",
+      "git commit*": "allow",
+      "git push*": "allow",
+      "composer test*": "allow",
+      "vendor/bin/phpunit*": "allow",
+      "php -l*": "allow"
+    }
+  },
+  "command": {
+    "fix-ci": {
+      "description": "Fix CI failure, test, commit, and push",
+      "agent": "build",
+      "template": "Fix the CI failure below. Treat /home/runner/work/core/core as the same repository as the current working directory. Find the first meaningful failure, patch the smallest correct fix, run relevant tests, run git diff --check, commit, and push.\n\n$ARGUMENTS"
+    }
+  }
+}

AGENTS.md

@@ -0,0 +1,115 @@
+# Core-Web — Agent Quick Reference
+
+## Working Loop
+
+When given a development task:
+
+1. Read the current git status.
+2. Review the relevant files.
+3. Create or update a TODO list.
+4. Implement one small safe change.
+5. Run the smallest relevant test first.
+6. Fix failures.
+7. Run broader tests when practical, preferably `composer test`.
+8. Run `git diff --check` before committing.
+9. Commit every successful code or documentation change.
+10. Push every successful commit to the current branch.
+11. If the task is not complete, continue with the next TODO instead of stopping.
+12. Only stop when:
+   - the task is fully complete and pushed,
+   - user approval is required,
+   - tests cannot proceed,
+   - git commit or git push fails,
+   - unrelated user changes would be overwritten,
+   - or a blocker is clearly documented.
+
+## Git / CI Discipline
+
+This repository is validated through GitHub Actions. The local working directory and the CI path refer to the same repository state:
+
+- Local path: `/Users/louis/Projects/LaswitchTech/core`
+- CI path: `/home/runner/work/core/core`
+
+When reviewing CI logs, mentally map `/home/runner/work/core/core` to the current local working directory.
+
+For every successful change:
+
+1. Run the relevant local test command.
+2. Run `git diff --check`.
+3. Review `git status`.
+4. Commit the change with a concise message.
+5. Push the commit to the current branch.
+
+Never stop after editing files without committing and pushing unless a blocker from the Working Loop applies.
+
+Do not claim that files cannot be edited, committed, or pushed unless the actual command fails.
+
+## Setup
+
+```sh
+composer install       # required before anything else
+composer test          # runs PHPUnit (tests/ Unit/*.php)
+vendor/bin/phpunit     # or run directly with config from phpunit.xml.dist
+```
+
+CI uses `PHP 8.2`. This is the minimum compatible version for dev work.
+
+## Structure at a glance
+
+- **`src/`** — Kernel framework classes (Bootstrap, Router, Database, Auth, etc.). 74 files total.
+- **`lib/plugins/`** — Domain feature plugins (auto-discovered via `info.cfg` manifests). ~57 plugins with lifecycle hooks.
+- **`lib/themes/`** — UI themes (default, gentelella, glass). LESS compilation via `Style.php` + `wikimedia/less.php`.
+- **`lib/modules/`** — Self-contained module packages.
+- **`config/*.cfg`** — JSON config files committed as defaults; instance-specific `.cfg` files are gitignored.
+- **`webroot/`** — Document root for advanced setups (gitignored per `.gitignore`).
+- **`cli`** — CLI entry point.
+- **`lib/skeleton/` + `lib/init.sh`** — Project scaffold boilerplate.
+
+## Bootstrap / Service Container
+
+```php
+new \LaswitchTech\Core\Bootstrap('ROUTER'); // loads globals: $DATABASE, $AUTH, $ROUTER, etc.
+new \LaswitchTech\Core\Bootstrap('API');    // routes + REST dispatching
+new \LaswitchTech\Core\Bootstrap('CLI');    // CLI runner
+```
+
+Services are injected into `$GLOBALS`. **Never instantiate services manually** outside Bootstrap — use the global instances the same way `index.php` does.
+
+## Routing & Entry Points
+
+- `index.php` — shared hosting entry point (loads `.env` inline for compatibility).
+- `webroot/index.php` — advanced deployment entry point (document root here).
+- `install.php` — web-based installer.
+- Routes are registered through `Router.php` and dispatched to controllers/plugins.
+
+## Key Constraints
+
+- **`.env` contains secrets** — never commit it. Use `.env.example` or documented environment variables instead.
+- **`vendor/`, `lib/` (except `.sh` files and `skeleton/`), `/Definition/`, `.DS_Store` are gitignored.** Plugin scaffolding lives in `lib/skeleton/`.
+- **`src/SMSP.php`, `src/IMAP.php`, `src/SLS.php`, etc. may be 0-byte stubs** — check before using; they are deferred features tracked in ROADMAP.md.
+- **PHP lint all files before committing** — CI runs `php -l` on every PHP file outside vendor/.
+- **PSR-12 is enforced** by CI via `git diff --check`. Follow it manually.
+
+## Testing
+
+```sh
+vendor/bin/phpunit                    # full suite (tests/Unit/*Test.php)
+vendor/bin/phpunit tests/Unit/RouterTest.php  # a single test file
+php -l src/SomeClass.php              # syntax check
+```
+
+Tests use `tests/bootstrap.php` which loads the Composer autoloader and defines `ROOT_PATH`. Unit tests have trait `tests/Traits/MockGlobals.php` for mocking globals.
+
+## Documentation Sources (read in this order)
+
+1. **AGENTS.md** — current agent workflow rules and repository-specific operating instructions
+2. **ROADMAP.md** — current priorities, gaps, V1.0 scope
+3. **DESIGN.md** — architecture decisions, service map, plugin/theme/layout contracts
+4. **docs/** — implemented behavior reference material
+
+## Repo-Specific Gotchas
+
+- `lib/plugins/` plugins use an auto-discovery lifecycle with `info.cfg` manifests. Don't hardcode plugin paths.
+- `Bootstrap.php` loads 25+ service globals scoped to ROUTER/API/CLI. Adding a new kernel service requires registering it in the relevant scope(s).
+- LESS/CSS build happens at runtime via `Style.php` — no build step or asset pipeline needed.
+- The CLI tool (`cli`) can create projects: `php cli core init`.

Command/CoreCommand.php

@@ -611,4 +611,124 @@ public function extensionAction()
                 return;
         }
     }
+
+    /**
+     * Start the PHP built-in server for local development
+     *
+     * Usage: php cli core serve [--port=8080]
+     */
+    public function serveAction(): void
+    {
+        // Parse arguments
+        $port = 8080;
+        $args = $this->Request->getArguments();
+        foreach ($args as $arg) {
+            if (str_starts_with($arg, '--port=')) {
+                $port = (int) substr($arg, 7);
+            }
+        }
+
+        $webroot = $this->Config->root() . DIRECTORY_SEPARATOR . 'webroot';
+
+        // Ensure webroot exists
+        if (!is_dir($webroot)) {
+            $this->Helper->Core->init(true);
+        }
+
+        $index = $webroot . DIRECTORY_SEPARATOR . 'index.php';
+        if (!is_file($index)) {
+            $this->Output->error('webroot/index.php not found. Run `php cli core init` first.');
+            return;
+        }
+
+        $this->Output->info("Starting PHP built-in server on http://localhost:{$port}");
+        $this->Output->info("Document root: {$webroot}");
+        $this->Output->info("Press Ctrl+C to stop");
+
+        // Start the PHP built-in server
+        $command = "php -S localhost:{$port} {$index}";
+
+        // Execute in foreground (allows Ctrl+C to stop)
+        passthru($command, $status);
+
+        if ($status !== 0) {
+            $this->Output->error("Server stopped with status {$status}");
+        }
+    }
+
+    /**
+     * Test all routes — list and verify they load
+     *
+     * Usage: php cli core test:routes [--verbose] [--format=json]
+     */
+    public function testRoutesAction(): void
+    {
+        global $CONFIG;
+
+        $verbose = in_array('--verbose', $this->Request->getArguments());
+        $format = 'text';
+        foreach ($this->Request->getArguments() as $arg) {
+            if (str_starts_with($arg, '--format=')) {
+                $format = substr($arg, 9);
+            }
+        }
+
+        // Collect all routes from all sources
+        $routes = [];
+
+        // App-level routes
+        $routesCfg = $CONFIG->root() . DIRECTORY_SEPARATOR . 'config' . DIRECTORY_SEPARATOR . 'routes.cfg';
+        if (is_file($routesCfg)) {
+            $content = file_get_contents($routesCfg);
+            if ($content) {
+                foreach (json_decode($content, true) as $namespace => $data) {
+                    $routes[$namespace] = ['source' => 'app', 'data' => $data];
+                }
+            }
+        }
+
+        // Plugin routes
+        $pluginsPath = $CONFIG->root() . DIRECTORY_SEPARATOR . 'lib' . DIRECTORY_SEPARATOR . 'plugins';
+        if (is_dir($pluginsPath)) {
+            foreach (array_diff(scandir($pluginsPath), array('..', '.')) as $plugin) {
+                $pluginPath = $pluginsPath . DIRECTORY_SEPARATOR . $plugin;
+                if (is_dir($pluginPath) && is_file($pluginPath . DIRECTORY_SEPARATOR . 'routes.cfg')) {
+                    $content = file_get_contents($pluginPath . DIRECTORY_SEPARATOR . 'routes.cfg');
+                    if ($content) {
+                        foreach (json_decode($content, true) as $namespace => $data) {
+                            $routes[$namespace] = ['source' => "plugin:{$plugin}", 'data' => $data];
+                        }
+                    }
+                }
+            }
+        }
+
+        if ($format === 'json') {
+            $this->Output->print(json_encode(['total' => count($routes), 'routes' => $routes], JSON_PRETTY_PRINT));
+            return;
+        }
+
+        $this->Output->info("=== Route Test Report ===");
+        $this->Output->print("Total routes: " . count($routes));
+        $this->Output->print("");
+
+        foreach ($routes as $namespace => $info) {
+            $data = $info['data'];
+            $public = $data['public'] ?? true;
+            $level = $data['level'] ?? 0;
+            $template = $data['template'] ?? 'none';
+            $view = $data['view'] ?? 'none';
+            $action = $data['action'] ?? 'none';
+
+            $status = $public ? 'PUBLIC' : 'PRIVATE (level ' . $level . ')';
+            $this->Output->print("  [{$status}] {$namespace} (template={$template}, view={$view}, action={$action}, source={$info['source']})");
+
+            if ($verbose) {
+                $this->Output->print("    Metadata: " . json_encode($data));
+            }
+        }
+
+        $this->Output->print("");
+        $this->Output->success("Route test complete.");
+    }
 }