@shaferllc/keel 0.12.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tom Shafer
+
+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,222 @@
+<div align="center">
+
+# Keel ⚓
+
+**The house framework for Node.js.**
+
+TypeScript · a real service container · convention-driven structure · a code-generating console.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+[![Node](https://img.shields.io/badge/node-%E2%89%A522-brightgreen.svg)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-3178c6.svg)](https://www.typescriptlang.org)
+
+[Getting Started](./docs/getting-started.md) ·
+[Container](./docs/container.md) ·
+[Routing](./docs/routing.md) ·
+[Providers](./docs/providers.md) ·
+[Console](./docs/console.md)
+
+</div>
+
+---
+
+Keel gives you the ergonomics that make you productive — a service container,
+service providers, dot-notation config, expressive routing, and a
+code-generating console — on a modern TypeScript stack. [Hono](https://hono.dev)
+powers the HTTP layer under the hood; everything above it is Keel's.
+
+It is a **house framework**: small enough to read in an afternoon, opinionated
+enough to ship on, and yours to extend.
+
+```ts
+// routes/web.ts
+router.get("/", [HomeController, "index"]);
+router.get("/hello/:name", (c) => c.text(`Hello, ${c.req.param("name")}!`));
+```
+
+```ts
+// A controller — resolved from the container, so it gets dependency injection
+export class HomeController {
+  constructor(private app: Container) {}
+
+  index(c: Ctx) {
+    return c.json({ app: config("app.name") });
+  }
+}
+```
+
+## Why Keel?
+
+- **A real service container.** `bind` / `singleton` / `instance` / `make`.
+  Everything resolves through it — the pattern that keeps apps testable and
+  composable.
+- **Service providers.** A `register()` → `boot()` lifecycle to configure the
+  app in one place.
+- **Convention over configuration.** `app/`, `config/`, `routes/`, `bootstrap/`
+  — you always know where things live.
+- **A code-generating console.** `keel serve`, `keel routes`, and `make:*`
+  generators.
+- **Typed end to end.** Strict TypeScript, no build step in dev (powered by
+  `tsx`).
+- **Thin and legible.** The whole framework is a few hundred lines in
+  `src/core/`. No magic you can't read.
+
+## Two repos: the framework and your app
+
+Keel is distributed the same way most frameworks are — a **library** you install,
+plus an **app** that depends on it:
+
+| Repo | Role |
+|------|------|
+| [`shaferllc/keel`](https://github.com/shaferllc/keel) (this repo) | The framework. Published as `@shaferllc/keel`. |
+| [`shaferllc/keel-app`](https://github.com/shaferllc/keel-app) | The starter app — clone it to build something. Gets core updates via `npm update`. |
+
+## Install in your app
+
+```bash
+npm install @shaferllc/keel
+```
+
+```ts
+import { Application, Router, config } from "@shaferllc/keel/core";
+```
+
+Or clone the [starter app](https://github.com/shaferllc/keel-app) and start
+from a working skeleton.
+
+## Hack on the framework itself
+
+```bash
+git clone https://github.com/shaferllc/keel.git
+cd keel
+npm install
+npm run dev            # example app on http://localhost:3000
+npm run build          # compile the package to dist/
+```
+
+```bash
+curl localhost:3000/            # HomeController@index (JSON)
+curl localhost:3000/ping        # inline closure route
+curl localhost:3000/hello/Tom   # route parameter
+```
+
+## The console
+
+```bash
+npm run keel routes                 # list every registered route
+npm run keel serve --port 8080      # start the server on a chosen port
+npm run keel make:controller Post   # -> app/Controllers/PostController.ts
+npm run keel make:provider Billing  # -> app/Providers/BillingServiceProvider.ts
+npm run keel make:middleware Auth   # -> app/Http/Middleware/authMiddleware.ts
+```
+
+Under the hood the console binary is `bin/keel.ts`; the npm scripts wrap it with
+`tsx`.
+
+## Project layout
+
+```
+src/core/            The framework (destined to become @keel/core on npm)
+├─ container.ts      Service container — bind / singleton / instance / make
+├─ application.ts    Kernel: env + config loading + provider lifecycle
+├─ config.ts         Dot-notation config repository + env() helper
+├─ provider.ts       ServiceProvider base class (register / boot)
+├─ http/
+│  ├─ router.ts      Route facade (closures or [Controller, method] tuples)
+│  └─ kernel.ts      Global middleware + compiles routes onto Hono
+├─ cli/              The `keel` console and make: stubs
+└─ index.ts          Public surface — userland imports "@keel/core"
+
+app/                 Your application code
+├─ Controllers/      Resolved from the container (dependency injection)
+├─ Providers/        Register + wire services
+└─ Http/
+   ├─ Kernel.ts      Register global middleware here
+   └─ Middleware/
+
+bootstrap/           createApplication(): boots providers, loads routes
+├─ app.ts
+└─ providers.ts      The list of providers to load
+
+config/              config/app.ts -> config('app.*')
+routes/web.ts        Route definitions
+```
+
+The `app/` vs `src/core/` split mirrors the classic application-vs-library
+separation: your code in `app/`, the framework in `src/core/`.
+
+## The request lifecycle
+
+1. `bin/keel.ts serve` calls `createApplication()` in `bootstrap/app.ts`.
+2. The `Application` loads `.env`, then every `config/*.ts` file, then runs each
+   provider's `register()` and `boot()`.
+3. The HTTP kernel (`app/Http/Kernel.ts`) applies global middleware and compiles
+   the collected routes onto a Hono instance.
+4. `@hono/node-server` serves it. Each request flows through middleware →
+   route handler (a closure or a container-resolved controller) → response.
+
+See [docs/architecture.md](./docs/architecture.md) for the full picture.
+
+## Documentation
+
+| Guide | What it covers |
+|-------|----------------|
+| [Getting Started](./docs/getting-started.md) | Install, run, first route and controller |
+| [The Service Container](./docs/container.md) | Binding and resolving services, DI |
+| [Service Providers](./docs/providers.md) | The register/boot lifecycle |
+| [Configuration](./docs/configuration.md) | `config/*.ts`, dot-notation, `env()` |
+| [Routing](./docs/routing.md) | Closures, controller tuples, parameters |
+| [Views](./docs/views.md) | Hono JSX components, layouts, the View service |
+| [Middleware](./docs/middleware.md) | Global middleware, writing your own |
+| [Errors](./docs/errors.md) | HTTP exceptions, debug page, custom handlers |
+| [Validation](./docs/validation.md) | `validate()` with Zod, auto-422 field errors |
+| [Inertia](./docs/inertia.md) | Server-side Inertia.js adapter |
+| [The Console](./docs/console.md) | `serve`, `routes`, `make:*` generators |
+| [Architecture](./docs/architecture.md) | Container, kernel, request lifecycle |
+
+## Testing
+
+The core has a test suite (Node's built-in runner + `tsx`, no extra tooling):
+
+```bash
+npm test              # run the suite
+npm run test:coverage # with v8 coverage
+```
+
+Unit tests cover the container, config, view, exceptions, and validation; an
+integration suite drives the HTTP kernel end-to-end (routing, request/response
+helpers, error rendering, middleware, validation). Coverage sits at **~99%
+lines / ~91% branches**.
+
+## Requirements
+
+- Node.js **≥ 22**
+- No database or build step required for the MVP core.
+
+## Roadmap
+
+Keel's first release is the **MVP core**: container, routing, middleware,
+config, and the console. On deck:
+
+- [x] View / templating layer (Hono JSX) — **v0.2.0**
+- [x] Cloudflare Workers–safe core — **v0.2.0**
+- [x] Global helpers: `config()`, `app()`, `view()` — **v0.3.0 / v0.4.0**
+- [x] Error & exception handling — **v0.5.0**
+- [x] Request/response + container helpers — **v0.6.0–v0.9.0**
+- [x] Validation (Zod-compatible) — **v0.10.0**
+- [x] First-class routing (groups, resources, named routes) — **v0.11.0**
+- [x] Domain routing, matchers, Inertia adapter — **v0.12.0**
+- [x] Test suite (~99% coverage)
+- [ ] ORM / query builder + migrations (wrapping Drizzle)
+- [ ] Queues (BullMQ), events, and mail
+- [ ] Publish `src/core` as the `@keel/core` package
+
+See [CHANGELOG.md](./CHANGELOG.md) for release history.
+
+## Contributing
+
+Issues and PRs welcome. Run `npm run typecheck` before opening a PR.
+
+## License
+
+[MIT](./LICENSE) © 2026 Tom Shafer

package/dist/core/application.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The Application is the container plus a lifecycle: it loads env + config,
+ * registers service providers, then boots them. This is Keel's kernel.
+ *
+ * The core is platform-neutral: Node built-ins (fs/path/url) and dotenv are
+ * imported dynamically and only when filesystem discovery is enabled, so the
+ * same Application runs under Node and on Cloudflare Workers. On Workers, call
+ * `boot(providers, { discoverConfig: false, config })` and pass config inline.
+ */
+import { Container } from "./container.js";
+import { Config, type ConfigData } from "./config.js";
+import { Router } from "./http/router.js";
+import { View } from "./view.js";
+import { type ProviderClass } from "./provider.js";
+export interface BootOptions {
+    /** Auto-load .env and config/*.ts from the filesystem. Default: true (Node). */
+    discoverConfig?: boolean;
+    /** Config to merge in directly — the way to configure on Workers. */
+    config?: ConfigData;
+}
+export declare class Application extends Container {
+    readonly basePath: string;
+    private providers;
+    private booted;
+    constructor(basePath?: string);
+    path(...segments: string[]): string;
+    config(): Config;
+    router(): Router;
+    view(): View;
+    /** Merge a config object into the repository under its top-level keys. */
+    private mergeConfig;
+    /** Load .env via dotenv (Node only; no-op elsewhere). */
+    private loadEnv;
+    /** Load every /config/*.ts file under its filename key (Node only). */
+    private loadConfig;
+    /** Register a provider instance (defers boot until boot()). */
+    register(Provider: ProviderClass): this;
+    /** Load config, register providers, then boot them. */
+    boot(providers?: ProviderClass[], options?: BootOptions): Promise<this>;
+}

package/dist/core/application.js

@@ -0,0 +1,115 @@
+/**
+ * The Application is the container plus a lifecycle: it loads env + config,
+ * registers service providers, then boots them. This is Keel's kernel.
+ *
+ * The core is platform-neutral: Node built-ins (fs/path/url) and dotenv are
+ * imported dynamically and only when filesystem discovery is enabled, so the
+ * same Application runs under Node and on Cloudflare Workers. On Workers, call
+ * `boot(providers, { discoverConfig: false, config })` and pass config inline.
+ */
+import { Container } from "./container.js";
+import { Config } from "./config.js";
+import { Router } from "./http/router.js";
+import { View } from "./view.js";
+import { setApplication } from "./helpers.js";
+export class Application extends Container {
+    basePath;
+    providers = [];
+    booted = false;
+    constructor(basePath = ".") {
+        super();
+        this.basePath = basePath;
+        // Make this the active application for global helpers (config(), app()).
+        setApplication(this);
+        // Core framework bindings (all platform-neutral).
+        this.instance(Application, this);
+        this.singleton(Config, () => new Config());
+        this.singleton(Router, (app) => new Router(app));
+        this.singleton(View, () => new View());
+    }
+    path(...segments) {
+        return [this.basePath, ...segments].join("/");
+    }
+    config() {
+        return this.make(Config);
+    }
+    router() {
+        return this.make(Router);
+    }
+    view() {
+        return this.make(View);
+    }
+    /** Merge a config object into the repository under its top-level keys. */
+    mergeConfig(data) {
+        const repo = this.make(Config);
+        for (const [key, value] of Object.entries(data)) {
+            repo.set(key, value);
+        }
+    }
+    /** Load .env via dotenv (Node only; no-op elsewhere). */
+    async loadEnv() {
+        try {
+            const [{ config }, { join }] = await Promise.all([
+                import("dotenv"),
+                import("node:path"),
+            ]);
+            config({ path: join(this.basePath, ".env") });
+        }
+        catch {
+            // Not on Node / no dotenv — fine.
+        }
+    }
+    /** Load every /config/*.ts file under its filename key (Node only). */
+    async loadConfig() {
+        try {
+            const [{ readdir }, { join }, { pathToFileURL }] = await Promise.all([
+                import("node:fs/promises"),
+                import("node:path"),
+                import("node:url"),
+            ]);
+            const dir = this.path("config");
+            const repo = this.make(Config);
+            const files = await readdir(dir);
+            for (const file of files) {
+                if (!/\.(ts|js|mjs)$/.test(file))
+                    continue;
+                const key = file.replace(/\.(ts|js|mjs)$/, "");
+                const mod = await import(pathToFileURL(join(dir, file)).href);
+                repo.set(key, mod.default ?? mod);
+            }
+        }
+        catch {
+            // No config dir or not on Node — fine.
+        }
+    }
+    /** Register a provider instance (defers boot until boot()). */
+    register(Provider) {
+        const provider = new Provider(this);
+        this.providers.push(provider);
+        return this;
+    }
+    /** Load config, register providers, then boot them. */
+    async boot(providers = [], options = {}) {
+        if (this.booted)
+            return this;
+        const { discoverConfig = true, config } = options;
+        if (discoverConfig) {
+            await this.loadEnv();
+            await this.loadConfig();
+        }
+        if (config) {
+            this.mergeConfig(config);
+        }
+        for (const Provider of providers) {
+            this.register(Provider);
+        }
+        for (const provider of this.providers) {
+            await provider.register();
+        }
+        for (const provider of this.providers) {
+            await provider.boot();
+        }
+        this.booted = true;
+        return this;
+    }
+}

package/dist/core/config.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Config repository with dot-notation access.
+ *
+ * Config files live in /config and export a default object. They are loaded
+ * at boot and merged under their filename: config/app.ts -> config('app.*').
+ */
+export type ConfigData = Record<string, unknown>;
+export declare class Config {
+    private items;
+    constructor(items?: ConfigData);
+    /** config('app.name') or config('app.name', 'Fallback'). */
+    get<T = unknown>(key: string, fallback?: T): T;
+    set(key: string, value: unknown): void;
+    all(): ConfigData;
+}
+/** Read an env var with an optional typed fallback (true/false/number coerced). */
+export declare function env<T = string>(key: string, fallback?: T): T;

package/dist/core/config.js

@@ -0,0 +1,55 @@
+/**
+ * Config repository with dot-notation access.
+ *
+ * Config files live in /config and export a default object. They are loaded
+ * at boot and merged under their filename: config/app.ts -> config('app.*').
+ */
+export class Config {
+    items;
+    constructor(items = {}) {
+        this.items = items;
+    }
+    /** config('app.name') or config('app.name', 'Fallback'). */
+    get(key, fallback) {
+        const segments = key.split(".");
+        let current = this.items;
+        for (const segment of segments) {
+            if (current !== null && typeof current === "object" && segment in current) {
+                current = current[segment];
+            }
+            else {
+                return fallback;
+            }
+        }
+        return current;
+    }
+    set(key, value) {
+        const segments = key.split(".");
+        const last = segments.pop();
+        let current = this.items;
+        for (const segment of segments) {
+            if (typeof current[segment] !== "object" || current[segment] === null) {
+                current[segment] = {};
+            }
+            current = current[segment];
+        }
+        current[last] = value;
+    }
+    all() {
+        return this.items;
+    }
+}
+/** Read an env var with an optional typed fallback (true/false/number coerced). */
+export function env(key, fallback) {
+    const raw = process.env[key];
+    if (raw === undefined)
+        return fallback;
+    if (raw === "true")
+        return true;
+    if (raw === "false")
+        return false;
+    if (raw !== "" && !Number.isNaN(Number(raw)) && typeof fallback === "number") {
+        return Number(raw);
+    }
+    return raw;
+}

package/dist/core/container.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The service container — the backbone of the framework.
+ *
+ * Everything (config, router, controllers, your own services) is resolved
+ * through here — it is the single registry every service resolves out of.
+ *
+ * Bindings are keyed by a string/symbol token OR a class constructor. A
+ * factory receives the container so it can resolve its own dependencies.
+ */
+export type Token<T = unknown> = string | symbol | Constructor<T>;
+export type Constructor<T = unknown> = new (...args: any[]) => T;
+export type Factory<T> = (app: Container) => T;
+export declare class Container {
+    private bindings;
+    private instances;
+    /** Register a transient binding — a fresh value every resolve. */
+    bind<T>(token: Token<T>, factory: Factory<T>): this;
+    /** Register a shared binding — resolved once, then cached. */
+    singleton<T>(token: Token<T>, factory: Factory<T>): this;
+    /** Register an already-constructed value as a shared instance. */
+    instance<T>(token: Token<T>, value: T): T;
+    /** True if the token is bound or has a cached instance. */
+    bound(token: Token): boolean;
+    /** Resolve a token out of the container. */
+    make<T>(token: Token<T>): T;
+    /** Instantiate a class, giving its constructor the container. */
+    build<T>(ctor: Constructor<T>): T;
+    /** Alias `app(token)` sugar over `make`. */
+    get<T>(token: Token<T>): T;
+}

package/dist/core/container.js

@@ -0,0 +1,59 @@
+/**
+ * The service container — the backbone of the framework.
+ *
+ * Everything (config, router, controllers, your own services) is resolved
+ * through here — it is the single registry every service resolves out of.
+ *
+ * Bindings are keyed by a string/symbol token OR a class constructor. A
+ * factory receives the container so it can resolve its own dependencies.
+ */
+export class Container {
+    bindings = new Map();
+    instances = new Map();
+    /** Register a transient binding — a fresh value every resolve. */
+    bind(token, factory) {
+        this.bindings.set(token, { factory, shared: false });
+        return this;
+    }
+    /** Register a shared binding — resolved once, then cached. */
+    singleton(token, factory) {
+        this.bindings.set(token, { factory, shared: true });
+        return this;
+    }
+    /** Register an already-constructed value as a shared instance. */
+    instance(token, value) {
+        this.instances.set(token, value);
+        return value;
+    }
+    /** True if the token is bound or has a cached instance. */
+    bound(token) {
+        return this.bindings.has(token) || this.instances.has(token);
+    }
+    /** Resolve a token out of the container. */
+    make(token) {
+        if (this.instances.has(token)) {
+            return this.instances.get(token);
+        }
+        const binding = this.bindings.get(token);
+        if (!binding) {
+            // Zero-arg classes can be auto-resolved without an explicit binding.
+            if (typeof token === "function") {
+                return this.build(token);
+            }
+            throw new Error(`Nothing bound in the container for [${String(token)}].`);
+        }
+        const resolved = binding.factory(this);
+        if (binding.shared) {
+            this.instances.set(token, resolved);
+        }
+        return resolved;
+    }
+    /** Instantiate a class, giving its constructor the container. */
+    build(ctor) {
+        return new ctor(this);
+    }
+    /** Alias `app(token)` sugar over `make`. */
+    get(token) {
+        return this.make(token);
+    }
+}

package/dist/core/exceptions.d.ts

@@ -0,0 +1,26 @@
+/**
+ * HTTP exceptions. Throw one of these anywhere in a handler, middleware, or
+ * service and the HTTP kernel turns it into the right response — a status code
+ * with a clean body (JSON or HTML), or a readable error page in debug mode.
+ */
+export declare const STATUS_TEXT: Record<number, string>;
+/** A semantic HTTP error carrying a status code and optional headers. */
+export declare class HttpException extends Error {
+    readonly status: number;
+    readonly headers?: Record<string, string>;
+    constructor(status: number, message?: string, headers?: Record<string, string>);
+}
+export declare class NotFoundException extends HttpException {
+    constructor(message?: string);
+}
+export declare class UnauthorizedException extends HttpException {
+    constructor(message?: string);
+}
+export declare class ForbiddenException extends HttpException {
+    constructor(message?: string);
+}
+/** 422 with per-field messages. Pairs with a future validation layer. */
+export declare class ValidationException extends HttpException {
+    readonly errors: Record<string, string[]>;
+    constructor(errors: Record<string, string[]>, message?: string);
+}

package/dist/core/exceptions.js

@@ -0,0 +1,56 @@
+/**
+ * HTTP exceptions. Throw one of these anywhere in a handler, middleware, or
+ * service and the HTTP kernel turns it into the right response — a status code
+ * with a clean body (JSON or HTML), or a readable error page in debug mode.
+ */
+export const STATUS_TEXT = {
+    400: "Bad Request",
+    401: "Unauthorized",
+    403: "Forbidden",
+    404: "Not Found",
+    405: "Method Not Allowed",
+    409: "Conflict",
+    419: "Page Expired",
+    422: "Unprocessable Entity",
+    429: "Too Many Requests",
+    500: "Internal Server Error",
+    503: "Service Unavailable",
+};
+/** A semantic HTTP error carrying a status code and optional headers. */
+export class HttpException extends Error {
+    status;
+    headers;
+    constructor(status, message, headers) {
+        super(message ?? STATUS_TEXT[status] ?? "Error");
+        this.name = "HttpException";
+        this.status = status;
+        this.headers = headers;
+    }
+}
+export class NotFoundException extends HttpException {
+    constructor(message = "Not Found") {
+        super(404, message);
+        this.name = "NotFoundException";
+    }
+}
+export class UnauthorizedException extends HttpException {
+    constructor(message = "Unauthorized") {
+        super(401, message);
+        this.name = "UnauthorizedException";
+    }
+}
+export class ForbiddenException extends HttpException {
+    constructor(message = "Forbidden") {
+        super(403, message);
+        this.name = "ForbiddenException";
+    }
+}
+/** 422 with per-field messages. Pairs with a future validation layer. */
+export class ValidationException extends HttpException {
+    errors;
+    constructor(errors, message = "The given data was invalid.") {
+        super(422, message);
+        this.name = "ValidationException";
+        this.errors = errors;
+    }
+}