Alpha

README.md

@@ -3,3 +3,206 @@
 [![Latest Version on Packagist](https://img.shields.io/packagist/v/flytachi/winter-kernel.svg)](https://packagist.org/packages/flytachi/winter-kernel)
 [![PHP Version Require](https://img.shields.io/packagist/php-v/flytachi/winter-kernel.svg?style=flat-square)](https://packagist.org/packages/flytachi/winter-kernel)
 [![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg)](LICENSE)
+
+The kernel of the Winter framework — a PHP 8.4 library that turns a directory of
+classes into a running application. It carries the HTTP layer, dependency injection,
+the database layer (PPA), managed processes and daemons, scheduling, and the console.
+
+It is a **library, not a skeleton**: there is nothing to scaffold and no directory tree
+to create. You add it to a project, write one class that says what the application
+contains, and run it.
+
+---
+
+## Requirements
+
+| | |
+|---|---|
+| PHP | **8.4+** |
+| Extensions | `pcntl`, `posix`, `fileinfo` (required) · `swoole` (for the HTTP server, coroutines and connection pooling) · `pdo` for a database |
+
+Everything else is pulled by composer.
+
+---
+
+## Install
+
+```bash
+composer require flytachi/winter-kernel
+```
+
+## The whole application: two files
+
+**`bootstrap.php`** — loads the autoloader and declares what the application contains:
+
+```php
+<?php
+declare(strict_types=1);
+
+use Flytachi\Winter\Kernel\App\Attribute\EnableWeb;
+use Flytachi\Winter\Kernel\WinterApplication;
+
+require __DIR__ . '/vendor/autoload.php';
+
+#[EnableWeb]
+final class Application extends WinterApplication
+{
+    public static function main(array $argv): never
+    {
+        parent::run($argv);
+    }
+}
+```
+
+**`call`** — the single entry point (make it executable with `chmod +x call`):
+
+```php
+#!/usr/bin/env php
+<?php
+chdir(__DIR__);
+require './bootstrap.php';
+Application::main($argv);
+```
+
+That is a working project. No `.env`, no directories — the kernel creates what it needs,
+when it needs it.
+
+```bash
+php call            # console: the command list
+php call run        # bring the application up
+php call run dev    # same, restarting on file changes
+```
+
+Add a controller anywhere under the project and it is found by the scan:
+
+```php
+use Flytachi\Winter\Kernel\Route\Annotation\GetMapping;
+use Flytachi\Winter\Kernel\Http\Stereotype\Controller;
+
+final class PingController extends Controller
+{
+    #[GetMapping('/ping')]
+    public function ping(): array
+    {
+        return ['pong' => true];
+    }
+}
+```
+
+---
+
+## What the application contains — `#[Enable*]`
+
+The attributes on the application class are the manifest. Each one adds a component;
+declare none and the boot fails rather than starting an application that does nothing.
+
+| Attribute | Effect |
+|---|---|
+| `#[EnableWeb]` | the Swoole HTTP server |
+| `#[EnableActuator]` | `/actuator` diagnostics (health, info, metrics, mappings) |
+| `#[EnableScheduler]` | runs `#[Scheduled]` methods on their triggers |
+| `#[EnableProcess(Foo::class)]` | a managed worker beside the server |
+| `#[EnableDaemon(Bar::class)]` | a supervised fleet of workers beside the server |
+| `#[EnableAsync]` | proxies `#[Async]` methods so they run off the request |
+| `#[Import('vendor/pkg', '/prefix')]` | mounts a plugin package under a URL prefix |
+
+Everything else is configured by ordinary classes the scan finds — there are no
+configuration hooks to override:
+
+```php
+#[Configuration] / #[Bean]   // DI factories
+WebConfigurer                // host, port, Swoole tuning, CORS, static files
+LoggingConfigurer            // extra log channels
+```
+
+---
+
+## Project layout
+
+Only two directories are conventional, and both are optional:
+
+```
+resources/
+  static/    web assets — served by Swoole when enabled (see WebConfigurer)
+  views/     view files — ResponseView's default root
+storage/
+  logs/ cache/ runnable/    created on demand, never committed
+```
+
+There is no `public/`: that belongs to the FPM document-root model, and the server here
+decides for itself what it serves. Static files are opt-in:
+
+```php
+final class WebConfig extends WebConfigurerAdapter
+{
+    public function configureServer(ServerSettings $server, ApplicationArguments $args): void
+    {
+        $server->port(8000)
+               ->staticPath('resources/static');   // resources/static/app.css → /app.css
+    }
+}
+```
+
+## Configuration
+
+`.env` is optional; every variable has a working default.
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `DEBUG` | `false` | verbose errors and a full rescan on every boot |
+| `LOG_LEVEL` | *(empty — logging off)* | `debug`…`emergency` |
+| `LOG_OUTPUT` | `auto` → stdout | `stdout`, `stderr`, `file`, `syslog`, `null` |
+| `LOG_FILE` | `storage/logs/<channel>.log` | absolute path when `LOG_OUTPUT=file` |
+| `SERVER_WORKERS` | Swoole default | worker count |
+| `WINTER_KEY` | *(none)* | signs payloads handed to background processes |
+| `PPA_POOL_TELEMETRY` | `5` | seconds between pool-stat publishes; `0` disables |
+
+---
+
+## Console
+
+```bash
+php call                       # command list
+php call run [dev]             # serve
+php call make -c UserController        # scaffold a class
+php call daemon  <dot.Class> start [-d] | stop | status
+php call process <dot.Class> start [-d] | stop | status
+php call db      ping | migrate | sql | pool
+php call schedule start [-d] | stop | status
+php call cfg     completion -i         # shell completion
+```
+
+Class names use dot notation: `main.process.Emails` → `Main\Process\Emails`.
+
+---
+
+## Runtimes
+
+The kernel runs the same application two ways:
+
+- **Swoole** — one long-lived server process; coroutines, connection pooling and static
+  files handled in C. This is the primary target.
+- **CLI / plain processes** — the console, and processes or daemons started on their own.
+
+FPM is not served by the kernel itself; it is moving to a separate `winter-fpm` project.
+
+---
+
+## Documentation
+
+- [`docs/starter/00-quickstart.md`](docs/starter/00-quickstart.md) — from an empty
+  directory to a served request, then to a background worker.
+- [`docs/`](docs) — the reference for each subsystem (routing, request binding,
+  responses, PPA, processes and daemons, scheduling, console, configuration).
+
+## Development
+
+```bash
+vendor/bin/phpunit                       # the default suite
+vendor/bin/phpunit --group integration   # real forks, signals and servers
+vendor/bin/phpcs                         # PSR-12
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

composer.json

@@ -15,25 +15,25 @@
     "autoload": {
         "psr-4": {
             "Flytachi\\Winter\\Console\\": "console/",
-            "Flytachi\\Winter\\K2\\": "src/"
+            "Flytachi\\Winter\\Kernel\\": "src/"
         },
         "files": [
             "function/dependencies.php"
         ]
     },
     "autoload-dev": {
         "psr-4": {
-            "Flytachi\\Winter\\K2\\Tests\\": "tests"
+            "Flytachi\\Winter\\Kernel\\Tests\\": "tests"
         }
     },
     "bin": ["wKernelRunner"],
     "require": {
         "php": ">=8.4",
-        "flytachi/winter-di": "^1.0",
+        "flytachi/winter-di": "^2.0",
         "flytachi/winter-base": "^3.0",
         "flytachi/winter-logger": "^1.0",
         "flytachi/winter-thread": "^3.0",
-        "flytachi/winter-cdo": "^3.0",
+        "flytachi/winter-cdo": "^4.0",
         "flytachi/winter-cache": "^1.0",
         "flytachi/file-store": "^2.0",
         "vlucas/phpdotenv": "^5.6",

console/Command/Cfg.php

@@ -5,9 +5,9 @@
 namespace Flytachi\Winter\Console\Command;
 
 use Flytachi\Winter\Console\Inc\Cmd;
-use Flytachi\Winter\K2\Kernel;
+use Flytachi\Winter\Kernel\Kernel;
 
-class Cfg extends Cmd
+final class Cfg extends Cmd
 {
     public static string $title = "manage project configuration, environment and keys";
     private string $templatePath;
@@ -200,37 +200,18 @@ private function envShow(): void
 
     private function dockerArg(): void
     {
-        $runtime = array_key_exists('swoole', $this->args['options']) ? 'swoole' : 'fpm';
-
-        // Single unified template: one stable Dockerfile + docker/ (fpm, swoole,
-        // dependencies.sh) + compose. The runtime is selected by the RUNTIME
-        // build arg, not by which files are copied.
+        // Flat Swoole template: Dockerfile + docker-compose.yml + docker/
+        // (entrypoint.sh, php-opcache.ini, dependencies/*.sh). dev vs prod is the
+        // DEV var in compose; DB drivers / extensions are the dependencies/ scripts.
         multiCopy($this->templatePath . '/Docker', Kernel::$pathRoot);
-        $this->setComposeRuntime($runtime);
 
-        self::printBadge('runtime', $runtime, 34, 36);
         self::printBadge('docker/', 'CREATED', 34, 32);
-        self::printBadge('docker/dependencies.sh', 'CREATED', 34, 32);
+        self::printBadge('docker/dependencies/', 'CREATED', 34, 32);
         self::printBadge('.dockerignore', 'CREATED', 34, 32);
         self::printBadge('docker-compose.yml', 'CREATED', 34, 32);
         self::printBadge('Dockerfile', 'CREATED', 34, 32);
-        self::printInfo("Switch runtime anytime: set RUNTIME (fpm|swoole) in docker-compose.yml");
-        self::printInfo("Add extensions/cron: edit docker/dependencies.sh");
-    }
-
-    /**
-     * Pin the default RUNTIME build arg in the freshly scaffolded compose file.
-     * The template ships `RUNTIME: fpm`; on `--swoole` we flip it to swoole so
-     * `docker compose build` picks the requested runtime out of the box.
-     */
-    private function setComposeRuntime(string $runtime): void
-    {
-        $compose = Kernel::$pathRoot . '/docker-compose.yml';
-        if (is_file($compose)) {
-            $content = file_get_contents($compose);
-            $content = preg_replace('/(RUNTIME:\s*)(?:fpm|swoole)/', '${1}' . $runtime, $content, 1);
-            file_put_contents($compose, $content);
-        }
+        self::printInfo("Run:  docker compose up  (dev, hot-reload)  |  DEV=false docker compose up  (prod)");
+        self::printInfo("DB drivers / extensions: keep or remove docker/dependencies/*.sh");
     }
 
     private function completionArg(): void
@@ -356,11 +337,11 @@ public static function help(): void
 
         // docker
         self::printLabel("docker — scaffold Docker files", $cl);
-        self::print("--fpm        default runtime = PHP-FPM + Nginx (default)", $cl);
-        self::print("--swoole     default runtime = Swoole HTTP server", $cl);
-        self::print("             one stable Dockerfile serves both; switch via", $cl);
-        self::print("             RUNTIME in docker-compose.yml. Extra packages,", $cl);
-        self::print("             redis/pgsql/mysql, cron → docker/dependencies.sh", $cl);
+        self::print("Swoole image. dev vs prod = DEV in docker-compose.yml:", $cl);
+        self::print("  docker compose up            dev (hot-reload, opcache off)", $cl);
+        self::print("  DEV=false docker compose up  prod (opcache on, no watcher)", $cl);
+        self::print("DB drivers / extensions / cron → docker/dependencies/*.sh", $cl);
+        self::print("  (keep or remove; bcmath, pgsql, mysql, redis shipped)", $cl);
         self::printLabel("docker — scaffold Docker files", $cl);
 
         // examples
@@ -372,9 +353,7 @@ public static function help(): void
         self::printInfo("call cfg env -i");
         self::printInfo("call cfg env -s");
         self::printInfo("call cfg env -s --file");
-        self::printInfo("call cfg docker           (fpm mode, default)");
-        self::printInfo("call cfg docker --fpm     (explicit fpm mode)");
-        self::printInfo("call cfg docker --swoole  (swoole mode)");
+        self::printInfo("call cfg docker           (scaffold Docker files)");
         self::printInfo("call cfg completion        (print scripts to stdout)");
         self::printInfo("call cfg completion -i     (install: ~/.zsh/completions/_call or ~/.bash_completion.d/call)");
         self::printInfo("call cfg completion -if    (force update installed file)");