@zerotal/core 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,79 @@
+# Changelog — @zerotal/core
+
+All notable changes to this package are documented here. The format is
+based on [Keep a Changelog](https://keepachangelog.com/); this package
+follows the Zerotal monorepo's unified versioning.
+
+**Maturity: `stable`**
+
+## [Unreleased]
+
+### Added
+
+- `@zerotal/core/storage` — file storage (local and S3-compatible disks) now
+  ships inside core. Previously the separate `@zerotal/storage` package, which
+  has been removed; import from `@zerotal/core/storage` instead. File writes are
+  not an optional concern — the logger's own trail, uploads, and the media
+  library all need one way to put bytes somewhere.
+- `Storage.publicUrl(path, { disk, expiresIn })` — a URL the browser can fetch,
+  with the kind chosen by the disk's own config: permanent for a served disk,
+  signed and expiring for a `signed` one, and `DiskNotServedError` for a disk
+  with no public URL. Handing back the stored path instead produced a _relative_
+  `src` that the browser resolved against the embedding page.
+- `Storage.isServed(disk?)` — branch a template without catching an error.
+- A served disk's URL base defaults to its `serve.path`, so `url()` and the
+  serving prefix cannot drift apart. An explicit `url` still wins, for a CDN.
+- File serving. A disk that declares `serve` in `config/storage.ts` is exposed
+  over HTTP by `StorageFilesMiddleware`; one without it has no URL at all. The
+  default `public` disk is served at `/storage`, the default `local` disk is not.
+  `serve.signed` requires a valid `temporaryUrl()` signature and answers a bad
+  one with `404` rather than `403`.
+- Private by default, with one public directory. Everything under the storage
+  root is private except `storage/public/`; a local disk rooted outside it can
+  only be served with `serve.signed`, and serving it openly throws
+  `UnsafePublicMountError` at boot. The default `public` disk now lives at
+  `storage/public` and is served at `/storage/public`, so the filesystem path
+  and the URL are the same shape.
+- The built-in disk roots derive from the storage root, so they follow
+  `ZT_STORAGE_ROOT` instead of hardcoding `./storage`.
+- The storage root. Every local disk must resolve inside `<project>/storage`
+  (or `ZT_STORAGE_ROOT`); one rooted elsewhere throws
+  `StorageRootEscapeError` at construction. The per-disk guard stops a path
+  escaping its disk; this stops the disk escaping the project.
+- `StorageDriver.stream?()` — an optional lazy handle, so serving a large file
+  does not read it into memory first. Implemented by `LocalDriver` and
+  `FakeDisk`; the middleware falls back to `getBuffer()` without it.
+- `StorageDriver.append()` — appends to a file, creating it when absent.
+  `LocalDriver` implements it natively; `S3Driver` throws
+  `UnsupportedOperationError`, since an S3 object is immutable and emulating an
+  append means rewriting the whole object.
+- Logging now writes to two always-on sinks: the terminal, and a date-rotated
+  file under `./storage/logs` kept for 14 days. Configure with `console` and
+  `file` in `config/logging.ts`; either can be set to `false`. The file trail is
+  off under `APP_ENV=test`.
+
+- Named log channels are now _additional_ destinations rather than the sole one.
+  An entry routed to a channel still reaches both sinks, except that a channel
+  already covering a sink suppresses that baseline for its own entries.
+- `LogManager` taps observe every entry, no longer filtered by the routed
+  channel's level — so an observer sees what the application logged, not what
+  one channel happened to accept.
+
+### Fixed
+
+- A facade returned from an `async` function no longer throws. The runtime reads
+  `.then` to test for a thenable, and the proxy answered by resolving the
+  container; `then`/`catch`/`finally` and the well-known symbols are now
+  answered without a lookup.
+
+## [1.0.0] — 2026-08-05
+
+_First public release._
+
+### Fixed
+
+- **`Application.withWebSocket()` multiplexes handlers by path** instead of last-write-wins. Previously a single `_wsHandlers`/`_wsUpgradeData` slot meant a second registration silently clobbered the first, so an app using both flow (`/__flow/ws`) and broadcasting (`/app/ws`) only got one working endpoint. Registrations are now stored per-path (with an optional catch-all); each connection is tagged with its request path on upgrade and open/message/close route to the matching handler. `withWebSocket(handlers, upgradeData?, path?)` gained an optional `path`.
+
+### Notes
+
+- Conforms to the Zerotal package conventions (provider in `src/provider/`, PascalCase config factory, `ZerotalError`-based errors, test coverage).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zerotal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,128 @@
+# @zerotal/core
+
+> The foundation of the Zerotal framework — IoC container, application lifecycle, HTTP pipeline, and the conventions everything else builds on.
+
+`@zerotal/core` is the heart of Zerotal, a Bun-native, full-stack TypeScript web framework. It owns the IoC container, the `Application` bootstrap/lifecycle engine, service providers, the router and HTTP pipeline, the typed config system, facades, events, JSX server-side views, and the console runtime. Every other Zerotal package (`@zerotal/orm`, `@zerotal/auth`, `@zerotal/session`, …) plugs into the primitives defined here.
+
+Part of the [Zerotal](../../README.md) framework. Requires **Bun ≥ 1.3.14** (uses Bun-native APIs).
+
+## Installation
+
+```bash
+bun add @zerotal/core
+```
+
+## What's inside
+
+- **Container** — an IoC container with singleton/scoped/transient/value lifetimes, `@inject()` auto-wiring, contextual bindings, aliases, resolution hooks, and per-request scopes via `AsyncLocalStorage`.
+- **Application** — the singleton that owns the container, discovers providers and config, loads routes, and drives the boot → start → stop lifecycle.
+- **Router** — explicit (`Router.get/post/resource/view/...`) and file-based routing into one router, with groups, named routes, model binding, and `route()` URL generation.
+- **Middleware** — the `Pipe` interface plus built-ins: `CorsMiddleware`, `ThrottleMiddleware`, `RateLimiter`, `SecureHeadersMiddleware`, `WebhookMiddleware`.
+- **HttpContext** — the per-request object holding the `Request`/`Response`, route params, authenticated user, and input/response helpers.
+- **Config** — a typed, dot-path config system (`config("app.name")`) backed by `config/*.ts` files, plus the `env()` helper for deployment state.
+- **Facades** — thin static accessors over container bindings; core ships `Config`, `Events`, and `Artisan`.
+- **Events** — a class-based event bus (`Emitter`) and a catalogue of framework events.
+- **Views** — a JSX server-side rendering runtime (`@zerotal/core/jsx-runtime`) with layouts, `safe()`/`esc()`, and `view()`.
+- **Commands** — the `Command` base class, `CommandRunner`, and a set of built-in CLI commands.
+- **Encryption / Hashing** — `Crypt` (authenticated encryption), `Hash` (password hashing), and signed-URL helpers.
+
+## Usage
+
+### Bootstrap an application
+
+```typescript
+// bootstrap/app.ts
+import { Application, basePath } from "@zerotal/core";
+
+export default Application.create().routing({ web: basePath("routes/web.ts") });
+```
+
+`Application.create()` builds the singleton once; providers under `app/providers/*` and config under `config/*.ts` are auto-discovered at boot. `currentApp()` returns it anywhere afterward.
+
+### Define routes
+
+```typescript
+import { Router } from "@zerotal/core";
+import { PostController } from "../app/controllers/PostController.ts";
+
+Router.get("/posts", PostController, "index");
+Router.get("/posts/:slug", PostController, "show").name("posts.show").bind("post", Post);
+Router.resource("articles", PostController);
+
+// Inline closure handler — no controller needed
+Router.get("/health", ({ http }) => http.json({ ok: true }));
+```
+
+### A controller using HttpContext
+
+```typescript
+import type { Context } from "@zerotal/core";
+import { Post } from "../models/Post.ts";
+
+export class PostController {
+  async index({ http }: Context): Promise<void> {
+    const posts = await Post.all();
+    http.json({ posts });
+  }
+
+  async store({ http }: Context): Promise<void> {
+    const { title, body } = await http.body<{ title: string; body: string }>();
+    const post = await Post.create({ title, body, userId: http.user!.id });
+    http.json(post, 201);
+  }
+}
+```
+
+### Bind and resolve from the container
+
+```typescript
+import { ServiceProvider, inject } from "@zerotal/core";
+
+export class AppServiceProvider extends ServiceProvider {
+  onRegister(): void {
+    this.app.container.singleton(CacheManager, async (c) => {
+      const cfg = await c.make("config");
+      return new CacheManager(cfg.get("cache"));
+    });
+  }
+}
+
+// Auto-wiring — declare constructor dependencies with @inject
+@inject(CacheManager)
+export class PostRepository {
+  constructor(private cache: CacheManager) {}
+}
+```
+
+### Read configuration
+
+```typescript
+import { config, env } from "@zerotal/core";
+
+config("app.name"); // typed as string via the ConfigRegistry
+config("app.port", 3000); // with a fallback
+const dbUrl = env("DATABASE_URL", "sqlite://./database.sqlite");
+```
+
+## Subpath exports
+
+| Import                        | Provides                                                                                                                                                                    |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@zerotal/core`               | The full public API: `Application`, `Container`, `Router`/`Route`, `HttpContext`, middleware, errors, events, config, facades, helpers, crypto, and view authoring helpers. |
+| `@zerotal/core/commands`      | Built-in console commands — `ServeCommand`, `WorkerCommand`, `KeyGenerateCommand`, `RouteListCommand`, the `Make*` scaffolders, and more.                                   |
+| `@zerotal/core/helpers`       | Standalone helper functions — `env`, `config`, `basePath`, `request`, `response` builders, `Str`, `Collection`, and pipe/tap utilities.                                     |
+| `@zerotal/core/facades`       | The built-in facades: `Config`, `Events`, `Artisan`.                                                                                                                        |
+| `@zerotal/core/macros/config` | The config macro used by the build tooling.                                                                                                                                 |
+| `@zerotal/core/jsx-runtime`   | The JSX runtime for server-side views — set `jsxImportSource: "@zerotal/core"` in tsconfig to use it.                                                                       |
+
+## Documentation
+
+- [Application lifecycle](../../docs/application.md)
+- [Container](../../docs/container.md)
+- [Routing](../../docs/routing)
+- [Controllers](../../docs/controllers.md)
+- [Middleware](../../docs/middleware.md)
+- [Context](../../docs/context.md)
+- [Service providers](../../docs/providers.md)
+- [Configuration](../../docs/config-system.md)
+- [Views](../../docs/view.md)

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@zerotal/core",
+  "version": "1.0.0",
+  "license": "MIT",
+  "maturity": "stable",
+  "private": false,
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./contracts": "./src/contracts/index.ts",
+    "./lock": "./src/lock/index.ts",
+    "./logger": "./src/logger/index.ts",
+    "./commands": "./src/command/builtin/index.ts",
+    "./helpers": "./src/helpers/index.ts",
+    "./facades": "./src/facade/facades/index.ts",
+    "./carbon": "./src/datetime/index.ts",
+    "./http": "./src/http/index.ts",
+    "./storage": "./src/storage/index.ts",
+    "./view": "./src/view/index.ts",
+    "./env": "./src/env/index.ts",
+    "./config": "./src/config/index.ts",
+    "./security": "./src/security/index.ts",
+    "./dev": "./src/dev/index.ts",
+    "./build": "./src/build/index.ts",
+    "./assets": "./src/assets/index.ts",
+    "./health": "./src/health/index.ts",
+    "./metrics": "./src/metrics/index.ts",
+    "./macros/config": "./src/macros/config.macro.ts",
+    "./jsx-runtime": "./src/view/jsx-runtime.ts",
+    "./jsx-dev-runtime": "./src/view/jsx-runtime.ts"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.spec.ts",
+    "!src/**/__fixtures__/**"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@js-temporal/polyfill": "^0.5.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.0"
+  },
+  "description": "The Zerotal framework core — application lifecycle, container, HTTP, routing, config, events, and helpers.",
+  "keywords": [
+    "zerotal",
+    "bun",
+    "typescript",
+    "framework"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zerotaldev/zerotal.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/zerotaldev/zerotal/tree/main/packages/core#readme",
+  "bugs": "https://github.com/zerotaldev/zerotal/issues"
+}