@objectstack/core 4.0.4 → 4.1.0

package/README.md

@@ -1,13 +1,18 @@
 # @objectstack/core
 
-The **Kernel** of the ObjectStack architecture. It provides the fundamental building blocks for a modular, plugin-based system.
+> ObjectStack microkernel — dependency injection, plugin lifecycle, event bus, and service registry for metadata-driven runtimes.
 
-## Features
+[![npm](https://img.shields.io/npm/v/@objectstack/core.svg)](https://www.npmjs.com/package/@objectstack/core)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-- **ObjectKernel**: A robust Dependency Injection (DI) container and plugin manager.
-- **Plugin Architecture**: A standard interface (`Plugin`) with lifecycle hooks (`init`, `start`, `stop`).
-- **Service Management**: Register and resolve services with type safety.
-- **Logging**: Structured logging interface with swappable backends.
+## Overview
+
+`@objectstack/core` is the foundation every ObjectStack runtime is built on. It hosts two kernels, a plugin lifecycle, a typed service registry, a structured logger, and a plugin-to-plugin event bus:
+
+- **`ObjectKernel`** — full-featured production kernel with hot reload, health monitoring, dependency resolution, and namespace isolation.
+- **`LiteKernel`** — minimal kernel for serverless, edge, and test environments.
+
+All other ObjectStack runtime packages (`runtime`, `rest`, `plugin-*`, `driver-*`, `service-*`) plug into a kernel instance.
 
 ## Installation
 
@@ -15,21 +20,101 @@ The **Kernel** of the ObjectStack architecture. It provides the fundamental buil
 pnpm add @objectstack/core
 ```
 
-## Basic Usage
+## Quick Start
 
 ```typescript
 import { ObjectKernel } from '@objectstack/core';
 
 const kernel = new ObjectKernel();
 
-// Register a simple plugin
 kernel.use({
   name: 'my-plugin',
   version: '1.0.0',
   async init(ctx) {
-    ctx.logger.info('Plugin initializing...');
-  }
+    ctx.logger.info('plugin initializing…');
+    ctx.registerService('greeter', { hello: (n: string) => `hi ${n}` });
+  },
+  async start(ctx) {
+    const svc = ctx.getService<{ hello: (s: string) => string }>('greeter')!;
+    ctx.logger.info(svc.hello('world'));
+  },
 });
 
 await kernel.bootstrap();
+// …
+await kernel.shutdown();
+```
+
+### LiteKernel (serverless/edge/tests)
+
+```typescript
+import { LiteKernel } from '@objectstack/core';
+
+const kernel = new LiteKernel();
+await kernel.bootstrap();
+```
+
+## Key Exports
+
+| Export | Kind | Description |
+|:---|:---|:---|
+| `ObjectKernel` | class | Production kernel with DI, lifecycle, event bus, hot reload, health monitor. |
+| `LiteKernel` | class | Minimal kernel for constrained runtimes. |
+| `Plugin` | interface | Plugin contract (`init`, `start`, `stop`, lifecycle hooks). |
+| `PluginContext` | interface | `{ logger, registerService, getService, eventBus, kernel }`. |
+| `ObjectLogger` | class | Structured logger over pino; swappable backends. |
+| `ApiRegistry` | class | Runtime route registry (consumed by `@objectstack/rest`). |
+| `QA` | namespace | Built-in kernel self-tests. |
+| `PackageManager` | class | Per-package DI namespace resolver. |
+
+## Plugin lifecycle
+
 ```
+use()  → init()  → start()  → [running]  → stop()  → unload()
+```
+
+- **`init(ctx)`** — register services, wire dependencies. Do not make network calls.
+- **`start(ctx)`** — resolve other services, begin work. Called after every plugin's `init()`.
+- **`stop(ctx)`** — graceful shutdown, flush, close connections.
+- **`kernel.unload(name)`** — runtime removal; pairs with `AppPlugin.onDisable()`.
+
+## Kernel choice
+
+| Kernel | Use when |
+|:---|:---|
+| `ObjectKernel` | Default. Production servers, Studio, tests that need plugin composition. |
+| `LiteKernel` | Cloudflare Workers, Vercel Edge, Vitest unit tests, footprint-sensitive sandboxes. |
+
+`EnhancedObjectKernel` has been **removed**. Migrate to `ObjectKernel`.
+
+## Observability
+
+- `ObjectLogger` is backed by pino; control verbosity with `LOG_LEVEL=info|debug|trace`.
+- `kernel.getHealth()` returns per-plugin health snapshots.
+- EventBus: `ctx.eventBus.on('plugin.started', …)`, `.emit(…)`.
+
+## When to use
+
+- ✅ Building an ObjectStack application (always).
+- ✅ Authoring a plugin, driver, or service.
+
+## When not to use
+
+- ❌ You only need the schemas — import [`@objectstack/spec`](../spec) alone.
+- ❌ You only need a REST client — import [`@objectstack/client`](../client).
+
+## Related Packages
+
+- [`@objectstack/spec`](../spec) — protocol definitions.
+- [`@objectstack/runtime`](../runtime) — `DriverPlugin` / `AppPlugin` scaffolds.
+- [`@objectstack/rest`](../rest) — auto-generated REST layer.
+
+## Links
+
+- 📖 Docs: <https://objectstack.ai/docs>
+- 📚 API Reference: <https://objectstack.ai/docs/references/kernel>
+- 🤖 Skill: [`skills/objectstack-plugin/SKILL.md`](../../skills/objectstack-plugin/SKILL.md)
+
+## License
+
+Apache-2.0 © ObjectStack