feat: create KoalaTs v3 application

.dependency-cruiser.cjs

@@ -23,13 +23,17 @@ module.exports = {
       severity: 'error',
       from: {
         path: '^src/packages/',
+        pathNot: '^src/packages/fastify-bridge/',
       },
       to: {
         path: '^node_modules/(?:@koa/router|koa|express|fastify)(?:/|$)',
       },
     },
   ],
   options: {
+    exclude: {
+      path: '(^|/)dist/',
+    },
     doNotFollow: {
       path: 'node_modules',
     },

.github/workflows/cd.yml

@@ -54,6 +54,9 @@ jobs:
       - name: Check code
         run: npm run lint
 
+      - name: Build
+        run: npm run build
+
       - name: Check types
         run: npm run typecheck
 
@@ -63,9 +66,6 @@ jobs:
       - name: Run tests
         run: npm run test
 
-      - name: Build
-        run: npm run build
-
       - name: Check packages
         run: npm run publint
 

.github/workflows/ci.yml

@@ -27,6 +27,9 @@ jobs:
       - name: Check code
         run: npm run lint
 
+      - name: Build
+        run: npm run build
+
       - name: Check types
         run: npm run typecheck
 
@@ -36,8 +39,5 @@ jobs:
       - name: Run tests
         run: npm run test
 
-      - name: Build
-        run: npm run build
-
       - name: Check packages
         run: npm run publint

docs/architecture/README.md

@@ -0,0 +1,69 @@
+# KoalaTs Architecture
+
+> [!NOTE]
+> This document describes the architecture of KoalaTs starting from the `v3` which is a work in progress and a
+> complete rewrite of the framework.
+
+## Overview
+
+KoalaTs is a monorepo made of three package types:
+
+- "Component": A standalone reusable library. It solves one focused problem and can be used without KoalaTs.
+- "Bridge": An integration layer between KoalaTs components and an external library or ecosystem.
+- "Bundle": The application-level composition of components and bridges.
+
+## Goals
+
+KoalaTs is a modern, easy-to-use, functional-programming-first framework. It separates application behavior from
+external runtime integrations.
+
+## Architecture
+
+### Framework Bundle
+
+The framework bundle is the composition root of an application. It combines components and bridges with an application
+manifest.
+
+```typescript
+koala(bridges)(manifest);
+```
+
+## Application composition
+
+```mermaid
+flowchart TD
+    Components["Components"]
+    Bridges["Bridges"]
+    Manifest["Application manifest"]
+    Bundle["Framework bundle"]
+    App["Koala application"]
+    Components --> Bundle
+    Bridges --> Bundle
+    Manifest --> Bundle
+    Bundle --> App
+```
+
+The bundle assembles an application from its manifest and the selected components and bridges.
+
+### Bridge examples
+
+| Bridge              | Connects                         |
+|---------------------|----------------------------------|
+| Fastify bridge      | HTTP component ↔ Fastify         |
+| Node console bridge | Console component ↔ Node process |
+
+## Application behavior
+
+An application can expose multiple entry points, such as HTTP, console, or MCP. Each entry point is supported by a
+component and connected to its runtime environment through a bridge.
+
+```mermaid
+flowchart LR
+    EntryPoints["Application entry points"]
+    Components["Components"]
+    Bridges["Bridges"]
+    Runtime["External runtime environments"]
+    EntryPoints --> Components
+    Components --> Bridges
+    Bridges --> Runtime
+```

makefile

@@ -1,16 +1,23 @@
 IMAGE_NAME ?= koalats-framework
+CONTAINER_NAME ?= $(IMAGE_NAME)-container
+HOST_PORT ?= 3000
 
-.PHONY: build bash start rebuild
+.PHONY: build bash start stop
 
-start: build bash
+start:
+	@if docker ps --format '{{.Names}}' | grep -qx $(CONTAINER_NAME); then \
+		echo "$(CONTAINER_NAME) is already running"; \
+	else \
+		docker run --rm --detach --name $(CONTAINER_NAME) --publish $(HOST_PORT):3000 --volume $(CURDIR):/app $(IMAGE_NAME) tail -f /dev/null; \
+	fi
 
 build:
-	@if ! docker images | grep -q $(IMAGE_NAME); then \
-		docker build -t $(IMAGE_NAME) . ; \
-	fi
+	docker build --no-cache -t $(IMAGE_NAME) .
 
 bash:
-	docker run --rm -it --name $(IMAGE_NAME)-container -v ${PWD}:/app $(IMAGE_NAME) /bin/sh
+	docker exec --interactive --tty $(CONTAINER_NAME) /bin/sh
 
-rebuild:
-	docker build --no-cache -t $(IMAGE_NAME) .
+stop:
+	@if docker container inspect $(CONTAINER_NAME) >/dev/null 2>&1; then \
+		docker rm --force $(CONTAINER_NAME); \
+	fi