@shaferllc/keel 0.68.0 → 0.77.0

package/dist/core/index.d.ts

@@ -4,9 +4,11 @@ export type { Token, Constructor, Factory } from "./container.js";
 export { Application } from "./application.js";
 export type { BootOptions, LifecycleHook, Configurator } from "./application.js";
 export { Config, env } from "./config.js";
+export { defineEnv, envVar, EnvValidationError } from "./env.js";
+export type { EnvRule, EnvSchema, EnvValues, EnvType, DefineEnvOptions } from "./env.js";
 export { app, config, view, bind, singleton, instance, make, bound, alias, swap, restore, events, emit, listen, cache, logger, onReady, onShutdown, terminate, } from "./helpers.js";
 export { Logger } from "./logger.js";
-export { consoleSink, MemorySink, setLogger, namedLogger } from "./logger.js";
+export { consoleSink, MemorySink, setLogger, namedLogger, tapLogs } from "./logger.js";
 export type { LogLevel, LoggerOptions, LogRecord, Sink, RedactOptions } from "./logger.js";
 export { requestLogger, requestLog } from "./request-logger.js";
 export type { RequestLoggerOptions } from "./request-logger.js";
@@ -16,6 +18,8 @@ export { Cache, MemoryStore } from "./cache.js";
 export type { CacheStore, RememberOptions, PutOptions } from "./cache.js";
 export { serveStatic } from "./static.js";
 export type { StaticOptions } from "./static.js";
+export { i18n, t, getI18n, setI18n, setTranslations, objectLoader, detectLocale, negotiateLocale, formatMessage, I18n, I18nManager, } from "./i18n.js";
+export type { Translations, TranslationsByLocale, TranslationLoader, I18nOptions, DetectLocaleOptions, } from "./i18n.js";
 export { lock, restoreLock, setLockStore, getLockStore, Lock, MemoryLockStore, LockNotHeldError, } from "./lock.js";
 export type { LockStore, AcquireOptions } from "./lock.js";
 export { health, healthCheck, check, Result, BaseCheck, HealthChecks, DatabaseCheck, RedisCheck, CacheCheck, } from "./health.js";
@@ -33,8 +37,8 @@ export { securityHeaders } from "./shield.js";
 export type { SecurityHeadersOptions, HstsOptions } from "./shield.js";
 export { csrf, csrfToken, csrfField } from "./csrf.js";
 export type { CsrfOptions } from "./csrf.js";
-export { db, connection, setConnection, addConnection, setDefaultConnection, connectionNames, clearConnections, QueryBuilder, } from "./database.js";
-export type { Connection, ConnectionHandle, WriteResult, Row, Dialect, Operator, Paginated } from "./database.js";
+export { db, connection, getConnection, setConnection, addConnection, setDefaultConnection, connectionNames, clearConnections, transaction, inTransaction, QueryBuilder, } from "./database.js";
+export type { Connection, TransactionConnection, TransactionHandle, ConnectionHandle, WriteResult, Row, Dialect, Operator, Paginated, } from "./database.js";
 export { Model } from "./model.js";
 export type { CastType, Casts } from "./casts.js";
 export { Relation, HasOne, HasMany, BelongsTo, BelongsToMany } from "./relations.js";
@@ -63,12 +67,29 @@ export { TemplateEngine, escapeHtml, templates, setTemplateEngine, render, } fro
 export type { Filter, RenderContext } from "./template.js";
 export { ServiceProvider } from "./provider.js";
 export type { ProviderClass } from "./provider.js";
+export { PackageProvider, MigrationRegistry, CommandRegistry, PublishRegistry, } from "./package.js";
+export type { PackageCommand, PublishEntry, PackageRouteOptions, PackageAssetOptions, PackageMiddleware, } from "./package.js";
+export { instrument, runRequest, currentRequestId, newRequestId, } from "./instrumentation.js";
+export type { QueryEvent, RequestEvent, ExceptionEvent, JobEvent, CacheEvent, NotificationEvent, ScheduleEvent, InstrumentEvent, } from "./instrumentation.js";
 export { Router, Route, RouteGroup, RouteResource, matchers } from "./http/router.js";
 export type { Ctx, RouteHandler, RouteDefinition, Method, Matcher, MiddlewareRef, UrlOptions, SignedUrlOptions, } from "./http/router.js";
 export { Inertia, inertia, inertiaPageAttr } from "./inertia.js";
 export type { InertiaPage, InertiaOptions } from "./inertia.js";
 export { HttpKernel } from "./http/kernel.js";
-export { TestClient, TestResponse, testClient } from "./testing.js";
+export { defineCommand, arg, flag, ConsoleKernel, ConsoleError, parseArgv } from "./console.js";
+export type { CommandDefinition, CommandContext, AnyCommand, ArgSpec, FlagSpec, ArgsSpec, FlagsSpec, ConsoleKernelOptions, } from "./console.js";
+export { createUi, stripAnsi } from "./console-ui.js";
+export type { Ui, UiOptions, Colors, ColorName, Table, Tasks, TaskHandle } from "./console-ui.js";
+export { createPrompt } from "./console-prompt.js";
+export type { Prompt, PromptOptions, ChoiceOptions, Choice, Trap } from "./console-prompt.js";
+export { startRepl } from "./repl.js";
+export type { ReplHelper, ReplOptions } from "./repl.js";
+export { pages, definePages, routePattern, routeName } from "./pages.js";
+export type { PageProps, PageModule, PagesOptions, RegisteredPage, PageMiddleware } from "./pages.js";
+export { TestClient, TestResponse, CommandResult, testClient, runCommand, resetState, freezeTime, timeTravel, restoreTime, timeIsFrozen, spy, spyOn, restoreSpies, truncate, assertDatabaseHas, assertDatabaseMissing, assertDatabaseCount, assertDatabaseEmpty, } from "./testing.js";
+export type { Spy } from "./testing.js";
+export { Tracer, Span, MemoryExporter, otlpExporter, consoleExporter, telemetry, setTelemetry, trace, currentSpan, setAttributes, addEvent, traceIds, flushTelemetry, tracing, parseTraceparent, traceparent, injectTraceContext, } from "./telemetry.js";
+export type { SpanContext, SpanData, SpanEvent, SpanKind, SpanStatus, SpanOptions, SpanExporter, SpanAttributes, SpanAttributeValue, TracerOptions, TracingOptions, OtlpOptions, } from "./telemetry.js";
 export { HttpException, BadRequestException, UnauthorizedException, PaymentRequiredException, ForbiddenException, NotFoundException, MethodNotAllowedException, NotAcceptableException, RequestTimeoutException, ConflictException, LengthRequiredException, ValidationException, TooManyRequestsException, ServerErrorException, NotImplementedException, BadGatewayException, ServiceUnavailableException, createError, STATUS_TEXT, } from "./exceptions.js";
 export { validate, validateRequest, validated } from "./validation.js";
 export type { Schema, RequestSchemas } from "./validation.js";

package/dist/core/index.js

@@ -2,13 +2,15 @@
 export { Container } from "./container.js";
 export { Application } from "./application.js";
 export { Config, env } from "./config.js";
+export { defineEnv, envVar, EnvValidationError } from "./env.js";
 export { app, config, view, bind, singleton, instance, make, bound, alias, swap, restore, events, emit, listen, cache, logger, onReady, onShutdown, terminate, } from "./helpers.js";
 export { Logger } from "./logger.js";
-export { consoleSink, MemorySink, setLogger, namedLogger } from "./logger.js";
+export { consoleSink, MemorySink, setLogger, namedLogger, tapLogs } from "./logger.js";
 export { requestLogger, requestLog } from "./request-logger.js";
 export { Events, EventBuffer } from "./events.js";
 export { Cache, MemoryStore } from "./cache.js";
 export { serveStatic } from "./static.js";
+export { i18n, t, getI18n, setI18n, setTranslations, objectLoader, detectLocale, negotiateLocale, formatMessage, I18n, I18nManager, } from "./i18n.js";
 export { lock, restoreLock, setLockStore, getLockStore, Lock, MemoryLockStore, LockNotHeldError, } from "./lock.js";
 export { health, healthCheck, check, Result, BaseCheck, HealthChecks, DatabaseCheck, RedisCheck, CacheCheck, } from "./health.js";
 export { Storage, FakeStorage, MemoryDisk, storage, setDisk, fakeDisk, restoreDisk, serveStorage, signStorageUrl, verifyStorageUrl, contentTypeFor, } from "./storage.js";
@@ -18,7 +20,7 @@ export { rateLimiter } from "./rate-limit.js";
 export { cors } from "./cors.js";
 export { securityHeaders } from "./shield.js";
 export { csrf, csrfToken, csrfField } from "./csrf.js";
-export { db, connection, setConnection, addConnection, setDefaultConnection, connectionNames, clearConnections, QueryBuilder, } from "./database.js";
+export { db, connection, getConnection, setConnection, addConnection, setDefaultConnection, connectionNames, clearConnections, transaction, inTransaction, QueryBuilder, } from "./database.js";
 export { Model } from "./model.js";
 export { Relation, HasOne, HasMany, BelongsTo, BelongsToMany } from "./relations.js";
 export { Faker, Factory as ModelFactory, factory, Seeder, seed } from "./factory.js";
@@ -34,10 +36,18 @@ export { decorateRequest, hasRequestDecorator, decorated, setRequestValue, clear
 export { View } from "./view.js";
 export { TemplateEngine, escapeHtml, templates, setTemplateEngine, render, } from "./template.js";
 export { ServiceProvider } from "./provider.js";
+export { PackageProvider, MigrationRegistry, CommandRegistry, PublishRegistry, } from "./package.js";
+export { instrument, runRequest, currentRequestId, newRequestId, } from "./instrumentation.js";
 export { Router, Route, RouteGroup, RouteResource, matchers } from "./http/router.js";
 export { Inertia, inertia, inertiaPageAttr } from "./inertia.js";
 export { HttpKernel } from "./http/kernel.js";
-export { TestClient, TestResponse, testClient } from "./testing.js";
+export { defineCommand, arg, flag, ConsoleKernel, ConsoleError, parseArgv } from "./console.js";
+export { createUi, stripAnsi } from "./console-ui.js";
+export { createPrompt } from "./console-prompt.js";
+export { startRepl } from "./repl.js";
+export { pages, definePages, routePattern, routeName } from "./pages.js";
+export { TestClient, TestResponse, CommandResult, testClient, runCommand, resetState, freezeTime, timeTravel, restoreTime, timeIsFrozen, spy, spyOn, restoreSpies, truncate, assertDatabaseHas, assertDatabaseMissing, assertDatabaseCount, assertDatabaseEmpty, } from "./testing.js";
+export { Tracer, Span, MemoryExporter, otlpExporter, consoleExporter, telemetry, setTelemetry, trace, currentSpan, setAttributes, addEvent, traceIds, flushTelemetry, tracing, parseTraceparent, traceparent, injectTraceContext, } from "./telemetry.js";
 export { HttpException, BadRequestException, UnauthorizedException, PaymentRequiredException, ForbiddenException, NotFoundException, MethodNotAllowedException, NotAcceptableException, RequestTimeoutException, ConflictException, LengthRequiredException, ValidationException, TooManyRequestsException, ServerErrorException, NotImplementedException, BadGatewayException, ServiceUnavailableException, createError, STATUS_TEXT, } from "./exceptions.js";
 export { validate, validateRequest, validated } from "./validation.js";
 export { Session, session, sessionMiddleware } from "./session.js";

package/dist/core/instrumentation.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Framework instrumentation — the typed event stream that lets a package observe
+ * the framework without patching it. Core seams (the query builder, the HTTP
+ * kernel, the queue, the cache, …) call `instrument(event, payload)`; anything
+ * that wants to watch subscribes with `listen()`. The mail layer already works
+ * this way (`mail.sent`); this generalises it.
+ *
+ * These events are deliberately fire-and-forget: `instrument()` never blocks the
+ * work it describes, and a listener that throws can't break a query or a
+ * request. That's the difference between instrumentation and business logic.
+ *
+ * A **request id** ties a request to everything that happened inside it — the
+ * queries it ran, the logs it wrote, the jobs it dispatched. The kernel opens a
+ * request scope with `runRequest(id, …)`; anything emitted inside it can read
+ * `currentRequestId()` to attribute itself. It flows through `await` chains via
+ * `AsyncLocalStorage`, so nothing has to be threaded by hand.
+ */
+/** A SQL statement that ran on a connection. */
+export interface QueryEvent {
+    sql: string;
+    bindings: unknown[];
+    /** Wall-clock time the statement took, in milliseconds. */
+    durationMs: number;
+    /** The registered connection name it ran on. */
+    connection: string;
+    /** "select" (row-returning) or "write" (insert/update/delete/DDL). */
+    kind: "select" | "write";
+    /** The request that ran it, if any. */
+    requestId?: string;
+}
+/** A request that finished (or threw). */
+export interface RequestEvent {
+    id: string;
+    method: string;
+    path: string;
+    status: number;
+    durationMs: number;
+    /** Request headers, lower-cased (auth/cookies are redacted by watchers). */
+    headers: Record<string, string>;
+    ip?: string;
+}
+/** An error that reached the HTTP kernel. */
+export interface ExceptionEvent {
+    error: unknown;
+    method?: string;
+    path?: string;
+    /** The status it rendered as. */
+    status: number;
+    requestId?: string;
+}
+/** A queued job at one point in its lifecycle. */
+export interface JobEvent {
+    job: string;
+    payload?: unknown;
+    /** Set on `job.processed` / `job.failed`. */
+    durationMs?: number;
+    /** Set on `job.failed`. */
+    error?: unknown;
+    requestId?: string;
+}
+/** A cache lookup. */
+export interface CacheEvent {
+    key: string;
+    store: string;
+    requestId?: string;
+}
+/** A notification that was sent. */
+export interface NotificationEvent {
+    notification: string;
+    channels: string[];
+    notifiable?: unknown;
+    requestId?: string;
+}
+/** A scheduled task that ran. */
+export interface ScheduleEvent {
+    task: string;
+    durationMs: number;
+}
+/**
+ * Register the instrumentation events on the framework's typed event registry,
+ * so `listen("db.query", (e) => …)` gets a fully-typed `e`. Any code that
+ * augments `EventsList` merges with this — declaring your own events elsewhere
+ * still works.
+ */
+declare module "./events.js" {
+    interface EventsList {
+        "db.query": QueryEvent;
+        "request.handled": RequestEvent;
+        "exception": ExceptionEvent;
+        "job.processing": JobEvent;
+        "job.processed": JobEvent;
+        "job.failed": JobEvent;
+        "cache.hit": CacheEvent;
+        "cache.miss": CacheEvent;
+        "notification.sent": NotificationEvent;
+        "schedule.task.run": ScheduleEvent;
+    }
+}
+/** The instrumentation event names, for iteration and toggling. */
+export type InstrumentEvent = "db.query" | "request.handled" | "exception" | "job.processing" | "job.processed" | "job.failed" | "cache.hit" | "cache.miss" | "notification.sent" | "schedule.task.run";
+/** A random id for a request/batch. 16 hex chars is plenty to be unique. */
+export declare function newRequestId(): string;
+/** Run `fn` inside a request scope, so everything it does can be attributed. */
+export declare function runRequest<T>(id: string, fn: () => T): T;
+/** The id of the request currently in scope, if any. */
+export declare function currentRequestId(): string | undefined;
+/**
+ * Emit an instrumentation event — fire-and-forget. Never throws, never blocks:
+ * a broken watcher can't take down the request it was watching, and the work
+ * being measured doesn't wait on the measurement. A no-op when there's no live
+ * application (e.g. a unit test that never booted one).
+ */
+export declare function instrument<E extends InstrumentEvent>(event: E, payload: import("./events.js").EventsList[E]): void;

package/dist/core/instrumentation.js

@@ -0,0 +1,52 @@
+/**
+ * Framework instrumentation — the typed event stream that lets a package observe
+ * the framework without patching it. Core seams (the query builder, the HTTP
+ * kernel, the queue, the cache, …) call `instrument(event, payload)`; anything
+ * that wants to watch subscribes with `listen()`. The mail layer already works
+ * this way (`mail.sent`); this generalises it.
+ *
+ * These events are deliberately fire-and-forget: `instrument()` never blocks the
+ * work it describes, and a listener that throws can't break a query or a
+ * request. That's the difference between instrumentation and business logic.
+ *
+ * A **request id** ties a request to everything that happened inside it — the
+ * queries it ran, the logs it wrote, the jobs it dispatched. The kernel opens a
+ * request scope with `runRequest(id, …)`; anything emitted inside it can read
+ * `currentRequestId()` to attribute itself. It flows through `await` chains via
+ * `AsyncLocalStorage`, so nothing has to be threaded by hand.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import { emit, hasApplication } from "./helpers.js";
+/* ------------------------------ request scope ----------------------------- */
+const store = new AsyncLocalStorage();
+/** A random id for a request/batch. 16 hex chars is plenty to be unique. */
+export function newRequestId() {
+    const bytes = new Uint8Array(8);
+    crypto.getRandomValues(bytes);
+    return [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+/** Run `fn` inside a request scope, so everything it does can be attributed. */
+export function runRequest(id, fn) {
+    return store.run({ id }, fn);
+}
+/** The id of the request currently in scope, if any. */
+export function currentRequestId() {
+    return store.getStore()?.id;
+}
+/* -------------------------------- emitting -------------------------------- */
+/**
+ * Emit an instrumentation event — fire-and-forget. Never throws, never blocks:
+ * a broken watcher can't take down the request it was watching, and the work
+ * being measured doesn't wait on the measurement. A no-op when there's no live
+ * application (e.g. a unit test that never booted one).
+ */
+export function instrument(event, payload) {
+    if (!hasApplication())
+        return;
+    try {
+        void Promise.resolve(emit(event, payload)).catch(() => { });
+    }
+    catch {
+        // hasApplication() raced with teardown — instrumentation stays silent.
+    }
+}

package/dist/core/logger.d.ts

@@ -66,6 +66,13 @@ export declare class MemorySink {
     messages(): string[];
     clear(): void;
 }
+/**
+ * Observe every log record emitted anywhere in the app. Returns an unsubscribe.
+ * A tap that throws is ignored — watching logs must never break logging.
+ *
+ *   const off = tapLogs((record) => store.record(record));
+ */
+export declare function tapLogs(sink: Sink): () => void;
 export declare class Logger {
     private options;
     private threshold;

package/dist/core/logger.js

@@ -93,6 +93,22 @@ export class MemorySink {
         this.records.length = 0;
     }
 }
+/**
+ * Sinks that observe *every* log record from *every* logger — an audit trail, a
+ * debug dashboard. Kept separate from a logger's own `sink` so tapping is
+ * non-invasive: it never changes where a log normally goes.
+ */
+const globalTaps = new Set();
+/**
+ * Observe every log record emitted anywhere in the app. Returns an unsubscribe.
+ * A tap that throws is ignored — watching logs must never break logging.
+ *
+ *   const off = tapLogs((record) => store.record(record));
+ */
+export function tapLogs(sink) {
+    globalTaps.add(sink);
+    return () => globalTaps.delete(sink);
+}
 export class Logger {
     options;
     threshold;
@@ -130,7 +146,18 @@ export class Logger {
                 fields = redactPath(fields, path.split("."), this.redact);
             }
         }
-        this.sink({ level, time: new Date().toISOString(), msg: message, fields });
+        const record = { level, time: new Date().toISOString(), msg: message, fields };
+        this.sink(record);
+        if (globalTaps.size) {
+            for (const tap of globalTaps) {
+                try {
+                    tap(record);
+                }
+                catch {
+                    // a tap must never break logging
+                }
+            }
+        }
     }
     trace(message, context) {
         this.write("trace", message, context);

package/dist/core/notification.js

@@ -20,6 +20,7 @@
 import { db } from "./database.js";
 import { getMailer } from "./mail.js";
 import { dispatch } from "./queue.js";
+import { instrument, currentRequestId } from "./instrumentation.js";
 export class Notification {
     /** Deliver from a queued job instead of inline. */
     shouldQueue = false;
@@ -103,8 +104,16 @@ export class Notifier {
     async send(notifiables, notification) {
         const recipients = Array.isArray(notifiables) ? notifiables : [notifiables];
         const run = async () => {
-            for (const recipient of recipients)
+            for (const recipient of recipients) {
                 await this.deliver(recipient, notification);
+                const requestId = currentRequestId();
+                instrument("notification.sent", {
+                    notification: notification.constructor.name,
+                    channels: notification.via(recipient),
+                    notifiable: recipient,
+                    ...(requestId ? { requestId } : {}),
+                });
+            }
         };
         if (notification.shouldQueue)
             await dispatch(run);

package/dist/core/package.d.ts

@@ -0,0 +1,117 @@
+/**
+ * The package system. Keel's `ServiceProvider` is already its plugin unit —
+ * `PackageProvider` is the same thing with batteries for the jobs a *shippable*
+ * package does over and over: merge its config defaults, register its routes and
+ * bundled UI assets, contribute migrations and console commands, and declare
+ * files a consuming app can publish. Each helper is a thin wrapper over an
+ * existing Keel primitive; the value is the convention, not new machinery.
+ *
+ *   export class WatchServiceProvider extends PackageProvider {
+ *     readonly name = "watch";
+ *     register() {
+ *       this.mergeConfig("watch", defaultConfig);
+ *       this.migrations([watchMigration]);
+ *       this.publishes({ [stub]: "config/watch.ts" }, "watch-config");
+ *     }
+ *     boot() {
+ *       this.assets("watch/assets", uiDir, { immutable: true });
+ *       this.routes((r) => registerWatchRoutes(r), { prefix: "watch", as: "watch" });
+ *     }
+ *   }
+ *
+ * A note on lifecycle: register/boot run *before* the app's HTTP kernel is bound
+ * (see `bootstrap/app.ts`), so a package must not reach for the kernel. That's
+ * why `routes()` and `assets()` go through the `Router` (bound in the
+ * Application constructor) — routes are compiled onto the kernel later, at build.
+ */
+import type { MiddlewareHandler } from "hono";
+import type { AnyCommand } from "./console.js";
+import { ServiceProvider } from "./provider.js";
+import type { Application } from "./application.js";
+import type { Router, RouteGroup, MiddlewareRef } from "./http/router.js";
+import type { Migration } from "./migrations.js";
+/**
+ * Every migration a package contributes, gathered in one place so `keel migrate`
+ * can run them alongside the app's own. Bound as a singleton on the Application.
+ */
+export declare class MigrationRegistry {
+    private list;
+    add(migrations: Migration[]): void;
+    all(): Migration[];
+}
+/** A console command a package adds to `keel`. */
+/**
+ * A command a package contributes to the console — the same `defineCommand()`
+ * shape an app uses, so a package's command gets typed args and flags, generated
+ * help, the terminal UI, and the prompt-trapping test story for free.
+ */
+export type PackageCommand = AnyCommand;
+/** Package-contributed console commands, mounted by the CLI after boot. */
+export declare class CommandRegistry {
+    private list;
+    add(commands: PackageCommand[]): void;
+    all(): PackageCommand[];
+}
+/** One `publishes()` declaration: source→destination files, optionally tagged. */
+export interface PublishEntry {
+    package: string;
+    tag?: string;
+    /** Absolute-or-package source path → app-relative destination path. */
+    files: Record<string, string>;
+}
+/** What `keel vendor:publish` copies into a consuming app. */
+export declare class PublishRegistry {
+    private entries;
+    add(entry: PublishEntry): void;
+    all(tag?: string): PublishEntry[];
+    tags(): string[];
+}
+export interface PackageRouteOptions {
+    /** Mount every route under this path prefix. */
+    prefix?: string;
+    /** Middleware to run before every route in the group. */
+    middleware?: MiddlewareRef | MiddlewareRef[];
+    /** Prefix every named route with `<as>.`. */
+    as?: string;
+}
+export interface PackageAssetOptions {
+    /** Cache-Control max-age (seconds). */
+    maxAge?: number;
+    /** Add `immutable` — for content-hashed filenames. */
+    immutable?: boolean;
+}
+export declare abstract class PackageProvider<O = Record<string, unknown>> extends ServiceProvider<O> {
+    /** The package's short name — used for publish grouping and diagnostics. */
+    abstract readonly name: string;
+    constructor(app: Application, options?: O);
+    /**
+     * Set config defaults under `key` without clobbering what the app already
+     * configured. Config files load before providers, so the app's `config/<key>.ts`
+     * (if any) is deep-merged *over* these defaults — the app always wins.
+     */
+    protected mergeConfig(key: string, defaults: Record<string, unknown>): void;
+    /**
+     * Register a group of routes. The callback receives the `Router`; the returned
+     * `RouteGroup` is already prefixed/guarded/named per `options`, and chainable
+     * for anything more.
+     */
+    protected routes(register: (router: Router) => void, options?: PackageRouteOptions): RouteGroup;
+    /**
+     * Serve a directory of static files (a bundled UI, images, …) under a URL
+     * prefix. Node-only. Mounts one wildcard route on the `Router`.
+     */
+    protected assets(urlPrefix: string, dir: string, options?: PackageAssetOptions): void;
+    /** Contribute migrations, run by `keel migrate` with the app's own. */
+    protected migrations(list: Migration[]): void;
+    /** Contribute console commands, mounted on `keel` after the app boots. */
+    protected commands(list: PackageCommand[]): void;
+    /**
+     * Declare files a consuming app can copy into itself with
+     * `keel vendor:publish` (optionally `--tag <tag>`): config stubs, views, etc.
+     * Keys are source paths (usually inside the package), values app-relative
+     * destinations.
+     */
+    protected publishes(files: Record<string, string>, tag?: string): void;
+}
+/** A middleware alias, re-exported so packages needn't reach into `hono`. */
+export type PackageMiddleware = MiddlewareHandler;

package/dist/core/package.js

@@ -0,0 +1,169 @@
+/**
+ * The package system. Keel's `ServiceProvider` is already its plugin unit —
+ * `PackageProvider` is the same thing with batteries for the jobs a *shippable*
+ * package does over and over: merge its config defaults, register its routes and
+ * bundled UI assets, contribute migrations and console commands, and declare
+ * files a consuming app can publish. Each helper is a thin wrapper over an
+ * existing Keel primitive; the value is the convention, not new machinery.
+ *
+ *   export class WatchServiceProvider extends PackageProvider {
+ *     readonly name = "watch";
+ *     register() {
+ *       this.mergeConfig("watch", defaultConfig);
+ *       this.migrations([watchMigration]);
+ *       this.publishes({ [stub]: "config/watch.ts" }, "watch-config");
+ *     }
+ *     boot() {
+ *       this.assets("watch/assets", uiDir, { immutable: true });
+ *       this.routes((r) => registerWatchRoutes(r), { prefix: "watch", as: "watch" });
+ *     }
+ *   }
+ *
+ * A note on lifecycle: register/boot run *before* the app's HTTP kernel is bound
+ * (see `bootstrap/app.ts`), so a package must not reach for the kernel. That's
+ * why `routes()` and `assets()` go through the `Router` (bound in the
+ * Application constructor) — routes are compiled onto the kernel later, at build.
+ */
+import { getMimeType } from "hono/utils/mime";
+import { ServiceProvider } from "./provider.js";
+import { NotFoundException } from "./exceptions.js";
+/* ------------------------------- registries ------------------------------- */
+/**
+ * Every migration a package contributes, gathered in one place so `keel migrate`
+ * can run them alongside the app's own. Bound as a singleton on the Application.
+ */
+export class MigrationRegistry {
+    list = [];
+    add(migrations) {
+        this.list.push(...migrations);
+    }
+    all() {
+        return [...this.list];
+    }
+}
+/** Package-contributed console commands, mounted by the CLI after boot. */
+export class CommandRegistry {
+    list = [];
+    add(commands) {
+        this.list.push(...commands);
+    }
+    all() {
+        return [...this.list];
+    }
+}
+/** What `keel vendor:publish` copies into a consuming app. */
+export class PublishRegistry {
+    entries = [];
+    add(entry) {
+        this.entries.push(entry);
+    }
+    all(tag) {
+        return tag ? this.entries.filter((e) => e.tag === tag) : [...this.entries];
+    }
+    tags() {
+        return [...new Set(this.entries.map((e) => e.tag).filter((t) => !!t))];
+    }
+}
+/* --------------------------------- helpers -------------------------------- */
+/** Deep-merge two plain objects; `override` wins, arrays are replaced wholesale. */
+function deepMerge(base, override) {
+    const out = { ...base };
+    for (const [key, value] of Object.entries(override)) {
+        const existing = out[key];
+        if (isPlainObject(existing) && isPlainObject(value)) {
+            out[key] = deepMerge(existing, value);
+        }
+        else {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * A route handler that serves files from `dir` for requests under `prefix`. Used
+ * by `PackageProvider.assets()` so a package can ship a built UI without the
+ * consuming app copying anything into `public/`. Node-only (uses `node:fs`);
+ * a miss becomes a 404 so it doesn't shadow real routes.
+ */
+function packageAssetHandler(prefix, dir, options) {
+    const root = dir.replace(/\/+$/, "");
+    return async (c) => {
+        const pathname = decodeURIComponent(new URL(c.req.url).pathname);
+        const rel = pathname.slice(prefix.length).replace(/^\/+/, "");
+        if (rel.includes(".."))
+            throw new NotFoundException();
+        const { stat, readFile } = await import("node:fs/promises");
+        const filePath = `${root}/${rel}`;
+        const stats = await stat(filePath).catch(() => null);
+        if (!stats?.isFile())
+            throw new NotFoundException();
+        const headers = {
+            "Content-Type": getMimeType(filePath) ?? "application/octet-stream",
+        };
+        if (options.maxAge != null) {
+            headers["Cache-Control"] =
+                `public, max-age=${options.maxAge}${options.immutable ? ", immutable" : ""}`;
+        }
+        return new Response(await readFile(filePath), { headers });
+    };
+}
+/* ----------------------------- PackageProvider ---------------------------- */
+export class PackageProvider extends ServiceProvider {
+    constructor(app, options) {
+        super(app, options);
+    }
+    /**
+     * Set config defaults under `key` without clobbering what the app already
+     * configured. Config files load before providers, so the app's `config/<key>.ts`
+     * (if any) is deep-merged *over* these defaults — the app always wins.
+     */
+    mergeConfig(key, defaults) {
+        const cfg = this.app.config();
+        const existing = cfg.get(key);
+        cfg.set(key, isPlainObject(existing) ? deepMerge(defaults, existing) : defaults);
+    }
+    /**
+     * Register a group of routes. The callback receives the `Router`; the returned
+     * `RouteGroup` is already prefixed/guarded/named per `options`, and chainable
+     * for anything more.
+     */
+    routes(register, options = {}) {
+        const router = this.app.router();
+        const group = router.group(() => register(router));
+        if (options.prefix)
+            group.prefix(options.prefix);
+        if (options.middleware)
+            group.middleware(options.middleware);
+        if (options.as)
+            group.as(options.as);
+        return group;
+    }
+    /**
+     * Serve a directory of static files (a bundled UI, images, …) under a URL
+     * prefix. Node-only. Mounts one wildcard route on the `Router`.
+     */
+    assets(urlPrefix, dir, options = {}) {
+        const prefix = "/" + urlPrefix.replace(/^\/|\/$/g, "");
+        this.app.router().get(`${prefix}/*`, packageAssetHandler(prefix, dir, options));
+    }
+    /** Contribute migrations, run by `keel migrate` with the app's own. */
+    migrations(list) {
+        this.app.make(MigrationRegistry).add(list);
+    }
+    /** Contribute console commands, mounted on `keel` after the app boots. */
+    commands(list) {
+        this.app.make(CommandRegistry).add(list);
+    }
+    /**
+     * Declare files a consuming app can copy into itself with
+     * `keel vendor:publish` (optionally `--tag <tag>`): config stubs, views, etc.
+     * Keys are source paths (usually inside the package), values app-relative
+     * destinations.
+     */
+    publishes(files, tag) {
+        this.app.make(PublishRegistry).add({ package: this.name, ...(tag ? { tag } : {}), files });
+    }
+}