@michaelthielemann/kestrel 4.1.3 → 5.0.0

package/README.md

@@ -1,201 +1,26 @@
-# Kestrel
-
-**Please be aware that this project is under rapid development and may not be suitable for long-term projects.**
-
-A slim, **static-site-generator CMS**: a generic collection-driven CRUD core with a schema-driven admin
-editor. You declare collections and fields in TypeScript; Kestrel derives the database, a typed CRUD API,
-and a full admin UI from those definitions, and renders published content to static HTML via
-`nuxt generate` — there is **no live public SSR**.
-
-Built on **Nuxt 4 layers + Drizzle/SQLite + Zod**. The whole CMS is a stack of swappable Nuxt layers, so
-a consumer extends it (`extends: ['@michaelthielemann/kestrel']`) and drops in their own collection/field/block definitions.
-
-## What Kestrel is — and isn't
-
-Kestrel is a **CMS engine**, not a finished website. It ships the admin UI, the schema/CRUD/render
-engines, and two toggleable built-in collections (`pages` + the `media` library); **you** define your
-content model and bring the public components and layout that render it.
-
-It is for a private editing origin that publishes **static HTML** (a local dir or S3), served by any
-static host. It is deliberately **not**:
-
-- **No live public SSR** — published pages are static (`nuxt generate` or the runtime incremental
-  publisher); there is no per-request rendering of the public site.
-- **Single-user** — one admin (session + CSRF). No roles, capabilities, or multi-user.
-- **SQLite only** — one database, single instance. (A Postgres `Dialect` seam exists; no impl is active.)
-- **No public data API** — only published *page-like* records have a read surface (mirroring the static
-  output); everything else stays behind the admin guard. No per-request rate limiting / live API.
-- **No runtime redirect engine** — redirects are *authored* in the CMS and published as a `redirects.json`
-  artifact, but Kestrel never answers a 30x itself; an edge (NGINX / njs / CloudFront) has to read it.
-- **No per-file access control on uploads.** The admin guard protects the media *library*, not the
-  bytes; the editing origin is meant to be non-public and published media is public by definition. See
-  [media.md](./docs/guide/media.md).
-
-## Features
-
-- **Runnable in one command** — `pnpm create kestrel` scaffolds a project that boots with a working
-  `/admin`, asking you to choose the admin password and writing its hash; `kestrel init` does the same to an
-  existing project without clobbering it, and `kestrel doctor` names whatever is still missing.
-- **Collection-driven** — declare collections + fields in TypeScript; Kestrel derives the SQLite tables, a
-  typed CRUD REST API, and the full admin UI. The schema **migrates itself** (additive in dev; explicit
-  `db:migrate` in prod).
-- **Field types** — twelve built in: text (single- or multi-line), slug, richtext, number, boolean,
-  datetime (date / time / range), choice (select / buttons / checkboxes), media, relation (single /
-  many), link (internal / external / email / tel), repeater (nestable), JSON — plus per-field `condition`
-  visibility rules. Register your own with `defineFieldType`.
-- **Page-like collections** — give a collection a `path`, SEO meta, and block or flat content; published
-  records render to static HTML and join the sitemap. **Singletons** for settings / navigation.
-- **Block page-builder** — a 3-pane editor (tree · live preview · fields) with nestable block slots; each
-  block is a single `app/blocks/*.vue` SFC (schema via field-factory `defineProps` + the display template).
-- **Media library** — upload (magic-byte sniff + SVG sanitize), local or S3 storage, responsive WebP
-  derivatives + thumbhash, folders, and a full-screen asset viewer. Optional **EU AI Act (Art. 50)
-  disclosure** fields per asset, with an upload-time scan for AI-origin signals (off by default).
-- **Multilingual content** — optional per-record translations, an editor locale flow, locale-prefixed
-  routing, hreflang alternates in the sitemap.
-- **Static output** — `nuxt generate` (full rebuild) or a runtime **incremental publisher** (re-renders
-  only the pages a write affects), to a local dir or S3; emits `sitemap.xml`, `robots.txt`,
-  **`llms.txt`** (an [llmstxt.org](https://llmstxt.org) site map so AI agents grasp the site) and
-  `redirects.json`. A live in-dashboard preview renders straight from the origin.
-- **Search + answer engines** — canonical / Open Graph / hreflang tags and a schema.org JSON-LD graph
-  (`WebSite` + `WebPage`/`Article` + `BreadcrumbList`) on every page, no wiring. Two opt-in extras publish
-  more than the page already showed: `seo.articleMeta` (author / publication date / keywords) and
-  `seo.llmsFull` (`/llms-full.txt`, every published page's body in one document).
-- **Reference integrity** — writes invalidate exactly the affected static pages; dead-reference warnings;
-  required + globally-unique page slugs per locale.
-
-## Quickstart (consumer)
-
-```bash
-pnpm create kestrel my-site
-cd my-site && pnpm install && pnpm dev
-```
-
-It asks you to choose an admin password and writes a project that runs as-is: `nuxt.config.ts` extending the
-meta-layer, an `app.vue` that renders, a `.env` holding a fresh session secret and the scrypt hash of
-your password, and one example block. Sign in at <http://localhost:3000/admin>.
-
-Already have a project? Run it in place — existing files are kept, `package.json` and `.env` are merged:
-
-```bash
-pnpm add @michaelthielemann/kestrel
-pnpm kestrel init      # completes the project
-pnpm kestrel doctor    # or just diagnose one that misbehaves
-```
-
-Installing the package **alone does nothing**: Nuxt only loads Kestrel once a config extends it. If you
-would rather wire it up by hand, that is two files:
-
-```ts
-// nuxt.config.ts
-export default defineNuxtConfig({
-  extends: ['@michaelthielemann/kestrel'],
-  kestrel: {
-    db: '.data/site.sqlite',
-    siteUrl: 'https://example.com',
-    siteName: 'Example',                // used in the generated llms.txt
-    locales: ['en', 'de'],
-    media: { uploadDir: '.data/uploads' },
-    // collections: { pages: false },   // drop a built-in to define your own with that name
-  },
-})
-```
-
-```ts
-// server/collections/products.ts — auto-discovered; the table is created on next boot
-export default defineCollection({
-  name: 'products',
-  mode: 'multi',
-  fields: { title: { type: 'text', required: true }, price: { type: 'number' }, image: { type: 'media' } },
-})
-```
-
-Set the auth env (`KESTREL_SESSION_SECRET`, `KESTREL_ADMIN_PASSWORD_HASH`), start the app, and manage
-content at `/admin`. You bring your own **public layout** and **block SFCs**
-(`app/blocks/Hero.vue` — one file for schema + display — is the `hero` block).
-
-> **Do not add an `app/app.vue` that omits `<NuxtPage />`.** A project-owned one shadows the layer's, and
-> the file `nuxi init` writes renders `<NuxtWelcome />` instead of your routes — the admin then appears to
-> be missing rather than blank. Kestrel reports this at build time; `kestrel doctor` catches it earlier.
-
-Full walkthrough: **[getting-started.md](docs/guide/getting-started.md)**.
-
-## Documentation
-
-Two doors, one per audience:
-
-- **[Guide](docs/guide/README.md)** — building a site with the package: collections, fields, blocks,
-  media, publishing, deployment, configuration, extension points.
-- **[Internals](docs/internals/README.md)** — developing Kestrel itself: architecture, layers and
-  packages, the pipeline engine, test rails, releasing, the ADR log.
-
-Most-asked pages: [getting started](docs/guide/getting-started.md) ·
-[field types](docs/guide/field-types.md) · [blocks](docs/guide/blocks.md) ·
-[configuration](docs/guide/configuration.md) · [deploying](docs/guide/deploying.md) ·
-[troubleshooting](docs/guide/troubleshooting.md).
-
-## Layout
-
-The domain/server code lives in ten `@michaelthielemann/kestrel-*` packages under `packages/` (`contracts`, `core`,
-`fields`, `auth`, `access`, `collections`, `media`, `publishing`, `delivery-live`, `delivery-static`).
-The nine Nuxt layers under `layers/` are thin wiring shells around those packages, except where a surface
-depends on Nuxt's own component resolution and auto-imports: the `ui` and `admin` layers (design system
-and editor SPA) and the `app/` halves of `media` and `public` stay real code in layers. Layers import
-packages by name; packages never import layers.
-
-`playground/` is a small consuming example, `templates/starter/` is what the scaffolder writes,
-`scripts/kestrel.mjs` is the CLI, and `packages/create-kestrel/` the `pnpm create kestrel` front end.
-The full map: [layers-and-packages.md](docs/internals/layers-and-packages.md).
-
-## Development
-
-Requires Node + [pnpm](https://pnpm.io).
-
-```bash
-pnpm install
-pnpm dev            # dev server (admin at /admin)
-pnpm build          # production build
-pnpm generate       # render the static public site to .output/public
-
-pnpm test           # node + happy-dom unit tests
-pnpm test:nuxt      # Nuxt-environment component tests
-pnpm test:e2e       # end-to-end tests (real dev server)
-pnpm lint           # ESLint (Nuxt-aware, generated from the playground)
-
-pnpm db:generate    # drizzle-kit: generate a migration
-pnpm db:migrate     # drizzle-kit: apply migrations
-pnpm hash-password  # produce a KESTREL_ADMIN_PASSWORD_HASH
-
-node scripts/kestrel.mjs init <dir>   # the consumer scaffolder, from a checkout
-node scripts/kestrel.mjs doctor <dir> # diagnose a consumer project
-```
-
-Conventions, test rails and the release flow: [internals/testing.md](docs/internals/testing.md) and
-[internals/releasing.md](docs/internals/releasing.md). Running a built site — production env, the static
-publisher, rehearsing a deploy locally: [deploying.md](docs/guide/deploying.md).
-
-## Configuration
-
-Non-auth settings live in `kestrel.config.ts` (`satisfies KestrelConfig`); each setting follows
-`KESTREL_* env → config → default`, resolved at build/dev start and frozen into `runtimeConfig` (a prebuilt
-server is retuned with the `NUXT_*` runtimeConfig names, not `KESTREL_*`). Auth/session secrets are
-**env-only** and read per request (`KESTREL_SESSION_SECRET`, `KESTREL_ADMIN_PASSWORD_HASH`, …). Full reference:
-[configuration.md](docs/guide/configuration.md).
-
-## Security
-
-Report vulnerabilities privately — see [SECURITY.md](SECURITY.md), which also lists the documented design
-decisions that are explicitly out of scope (uploads are not access-controlled; the editing origin is
-assumed to be non-public).
-
-## Licence
-
-Apache License 2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE). You may use, modify and distribute
-Kestrel, including commercially and in closed-source work, as long as you keep the copyright notice and
-the licence, state significant changes you make to the files, and pass the NOTICE along. The licence
-grants patent rights but **no trademark rights**: the name "Kestrel" and the project's branding are not
-covered, so a fork needs its own name.
-
-Kestrel is provided free of charge, developed and published outside any commercial activity, **with no
-warranty and no commercial support** (see sections 7 and 8 of the licence). If you need guarantees for a
-production deployment, the honest answer is to read the code, run the test suite, and decide for yourself
-— that is what the licence terms mean in practice.
+# @michaelthielemann/kestrel
+The core: `defineContract`, `defineModule`, `definePipeline`, `defineConfig`, the boot check and
+the pipeline runner with HTTP, event and cron triggers. It ships no contracts and no modules;
+a config without modules boots as an empty shell. `boot()` reads the config, sorts modules by
+`requires`, runs `setup()`, checks every provided contract's methods, registers steps, resolves
+pipelines and validates triggers; any problem throws `KestrelBootError { module, reason }`.
+The `kestrel` binary loads `kestrel.config.ts`, the modules named in `use` and `pipelines/*.ts`
+from the current directory. `testing/runPipeline` runs a pipeline against fake steps.
+Binary results are served `inline` for a built-in safe set of content types plus any listed in `http.inlineTypes`.
+`http.inlineTypes` with `image/svg+xml` needs a module registering the step `sanitize.svg`
+(`sanitize-svg`), otherwise boot fails.
+
+## HTTP config
+`http` takes `port`, `host`, `corsOrigin`, `maxBodyBytes`, `trustProxy`, `healthPath`, `inlineTypes`
+and `timeouts: { requestMs, headersMs, keepAliveMs }` (defaults 30000 / 10000 / 5000), which map to
+`server.requestTimeout`, `server.headersTimeout` and `server.keepAliveTimeout`. An incoming
+`x-request-id` header of short printable ASCII becomes `ctx.requestId`, appears in the `http` log
+line and is echoed as the `x-request-id` response header next to `x-kestrel-run-id`.
+
+## Shutdown
+`stop()` closes the listener, waits for the in-flight runs and for connections still sending a
+request or receiving a response, then drops the remaining connections, stops the cron and event
+triggers and tears the modules down in reverse boot order. The deadline is `stop({ timeoutMs })`
+or the top-level config `shutdownTimeoutMs` (default 30000); the returned `{ drained }` says whether
+everything finished inside it. The `kestrel` binary wires SIGINT/SIGTERM to `stop()` (exit 1 when the
+deadline is hit) and logs `unhandledRejection`/`uncaughtException` before stopping and exiting 1.

package/dist/boot.d.ts

@@ -0,0 +1,45 @@
+import type { AddressInfo } from "node:net";
+import type { ContextInput } from "./context.ts";
+import { type KestrelConfig, type KestrelConfigInput } from "./defineConfig.ts";
+import { type Deps, type EventEntry, type ModuleDefinition } from "./defineModule.ts";
+import type { PipelineDefinition } from "./definePipeline.ts";
+import { type Logger } from "./logger.ts";
+import { StepRegistry } from "./registry.ts";
+import { type ResolvedPipeline, type RunResult } from "./runner.ts";
+import { type CronEntry } from "./triggers/cron.ts";
+import { type Route } from "./triggers/http.ts";
+export interface BootInput {
+    config: KestrelConfigInput;
+    modules: readonly ModuleDefinition[];
+    pipelines: readonly PipelineDefinition[];
+    logger?: Logger;
+    root?: string;
+    /** Validates `ctx.payload` against `describe().input` before every step; defaults to `NODE_ENV !== "production"`. */
+    dev?: boolean;
+}
+export interface Triggers {
+    http: readonly Route[];
+    events: readonly EventEntry[];
+    crons: readonly CronEntry[];
+}
+export interface StopOptions {
+    timeoutMs?: number;
+}
+export interface StopResult {
+    drained: boolean;
+}
+export interface Kestrel {
+    config: KestrelConfig;
+    contracts: Deps & {
+        names(): string[];
+    };
+    steps: StepRegistry;
+    pipelines: ReadonlyMap<string, ResolvedPipeline>;
+    triggers: Triggers;
+    run(pipeline: string, input: ContextInput): Promise<RunResult>;
+    start(): Promise<{
+        http?: AddressInfo;
+    }>;
+    stop(options?: StopOptions): Promise<StopResult>;
+}
+export declare function boot(input: BootInput): Promise<Kestrel>;

package/dist/boot.js

@@ -0,0 +1,274 @@
+import { missingMethods } from "./defineContract.js";
+import { checkDataflow } from "./dataflow.js";
+import { configSchema } from "./defineConfig.js";
+import { stepPrefix } from "./defineModule.js";
+import { KestrelBootError } from "./errors.js";
+import { consoleLogger } from "./logger.js";
+import { StepRegistry } from "./registry.js";
+import { createRunTracker, runPipeline } from "./runner.js";
+import { sortModules } from "./sort.js";
+import { createCronEntry, startCron } from "./triggers/cron.js";
+import { createHttpServer, listen, parseRoute, routePattern } from "./triggers/http.js";
+const CORE = "kestrel";
+const SVG = "image/svg+xml";
+const SANITIZE_SVG = "sanitize.svg";
+const BARREL = new Set(["module", "index", "src", "dist"]);
+/** `use` is a package name or a path and never equals `mod.name`; both "@scope/kestrel-authn-multi" and "./modules/authn/multi/module.ts" reduce to ["authn", "multi"]. */
+function useTokens(use) {
+    const parts = (use.split(/[?#]/)[0] ?? use).split("/").filter((p) => p !== "" && p !== "." && p !== "..");
+    if (parts[0]?.startsWith("@"))
+        parts.shift();
+    const tokens = parts.flatMap((p) => p.replace(/\.[cm]?[jt]sx?$/, "").toLowerCase().split("-")).filter((t) => t !== "");
+    while (BARREL.has(tokens.at(-1) ?? ""))
+        tokens.pop();
+    if (tokens[0] === "kestrel")
+        tokens.shift();
+    return tokens;
+}
+function entryNamesModule(use, moduleName) {
+    const tokens = useTokens(use);
+    if (tokens.length === 0)
+        return false;
+    const wanted = moduleName.split("/");
+    // Too few tokens to spell out "<module>/<submodule>": accept a hit on either half, which still
+    // separates any two modules whose names differ in that half.
+    if (tokens.length < wanted.length)
+        return wanted.includes(tokens[tokens.length - 1]);
+    return wanted.every((w, i) => tokens[tokens.length - wanted.length + i] === w);
+}
+function settledWithin(promise, ms) {
+    if (ms <= 0)
+        return Promise.resolve(false);
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(false), ms);
+        timer.unref();
+        void promise.then(() => {
+            clearTimeout(timer);
+            resolve(true);
+        });
+    });
+}
+/** A connection that goes idle after close() would otherwise hold the server until keepAliveTimeout. */
+async function drainConnections(server, closing, deadline) {
+    let closed = false;
+    void closing.then(() => {
+        closed = true;
+    });
+    while (!closed && Date.now() < deadline) {
+        server.closeIdleConnections();
+        await settledWithin(closing, Math.min(50, deadline - Date.now()));
+    }
+    return closed;
+}
+async function teardownAll(ordered, instances, logger) {
+    for (const mod of [...ordered].reverse()) {
+        if (!mod.teardown || !instances.has(mod))
+            continue;
+        try {
+            await mod.teardown(instances.get(mod));
+        }
+        catch (err) {
+            logger.error(`teardown failed for module "${mod.name}"`, { module: mod.name, error: err instanceof Error ? err.message : String(err) });
+        }
+    }
+}
+export async function boot(input) {
+    const logger = input.logger ?? consoleLogger;
+    const root = input.root ?? process.cwd();
+    const dev = input.dev ?? process.env.NODE_ENV !== "production";
+    const parsed = configSchema.safeParse(input.config);
+    if (!parsed.success)
+        throw new KestrelBootError(CORE, `invalid kestrel.config: ${parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`);
+    const config = parsed.data;
+    if (input.modules.length !== config.modules.length)
+        throw new KestrelBootError(CORE, `config lists ${config.modules.length} modules but ${input.modules.length} were loaded`);
+    const configByModule = new Map();
+    const seen = new Set();
+    input.modules.forEach((mod, i) => {
+        const entry = config.modules[i];
+        if (seen.has(mod.name))
+            throw new KestrelBootError(mod.name, `listed twice in kestrel.config (${entry.use})`);
+        seen.add(mod.name);
+        if (!entryNamesModule(entry.use, mod.name)) {
+            // A `use` that names no loaded module at all is not evidence of anything — third-party
+            // packages need not be named after their module. Only a hit on a different one is.
+            const other = input.modules.find((m) => m !== mod && entryNamesModule(entry.use, m.name));
+            if (other)
+                throw new KestrelBootError(CORE, `config.modules[${i}] "${entry.use}" names module "${other.name}", not "${mod.name}"; config entries and loaded modules must be in the same order`);
+        }
+        configByModule.set(mod, entry.config ?? {});
+    });
+    const ordered = sortModules(input.modules);
+    for (const mod of ordered) {
+        if (mod.provides.length === 0)
+            continue;
+        const prefix = stepPrefix(mod.name);
+        if (mod.provides.some((c) => c.name.split("@")[0] === prefix))
+            continue;
+        throw new KestrelBootError(mod.name, `provides ${mod.provides.map((c) => `"${c.name}"`).join(", ")} but registers steps under "${prefix}."; a module must be named after a contract it provides`);
+    }
+    const registered = new Map();
+    const contracts = {
+        get(contract) {
+            if (!registered.has(contract.name))
+                throw new Error(`no provider for "${contract.name}"`);
+            return registered.get(contract.name);
+        },
+        find(contract) {
+            return registered.get(contract.name);
+        },
+        names: () => [...registered.keys()],
+        logger,
+        root,
+    };
+    const instances = new Map();
+    try {
+        for (const mod of ordered) {
+            const cfg = mod.configSchema.safeParse(configByModule.get(mod));
+            if (!cfg.success)
+                throw new KestrelBootError(mod.name, `invalid config: ${cfg.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+            let instance;
+            try {
+                instance = await mod.setup(cfg.data, contracts);
+            }
+            catch (err) {
+                throw new KestrelBootError(mod.name, `setup() threw: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            instances.set(mod, instance);
+            for (const contract of mod.provides) {
+                const missing = missingMethods(contract, instance);
+                if (missing.length > 0)
+                    throw new KestrelBootError(mod.name, `setup() result lacks ${contract.name} method(s): ${missing.join(", ")}`);
+                registered.set(contract.name, instance);
+            }
+        }
+        const steps = new StepRegistry();
+        for (const mod of ordered) {
+            if (!mod.steps)
+                continue;
+            steps.register(mod.name, stepPrefix(mod.name), mod.steps(instances.get(mod)), mod.describe?.(instances.get(mod)) ?? {});
+        }
+        if (config.http?.inlineTypes.includes(SVG) && !steps.has(SANITIZE_SVG)) {
+            throw new KestrelBootError(CORE, `http.inlineTypes contains "${SVG}" but no module registers the step "${SANITIZE_SVG}"`);
+        }
+        const definitions = new Map();
+        for (const p of input.pipelines) {
+            if (definitions.has(p.name))
+                throw new KestrelBootError(`pipelines/${p.name}`, "defined twice");
+            definitions.set(p.name, p);
+        }
+        const pipelines = new Map();
+        for (const def of definitions.values()) {
+            if (def.steps.length === 0)
+                throw new KestrelBootError(`pipelines/${def.name}`, "has no steps");
+            pipelines.set(def.name, { name: def.name, steps: def.steps.map((s) => steps.resolve(s, `pipelines/${def.name}`)) });
+        }
+        const routes = [];
+        const events = [];
+        const crons = [];
+        const byPattern = new Map();
+        for (const t of config.triggers) {
+            if (!pipelines.has(t.pipeline))
+                throw new KestrelBootError(CORE, `trigger references unknown pipeline "${t.pipeline}"`);
+            let route;
+            try {
+                if ("http" in t)
+                    route = parseRoute(t.http, t.pipeline);
+                else if ("event" in t)
+                    events.push({ event: t.event, pipeline: t.pipeline });
+                else
+                    crons.push(createCronEntry(t.cron, t.pipeline));
+            }
+            catch (err) {
+                throw new KestrelBootError(CORE, `invalid trigger for "${t.pipeline}": ${err instanceof Error ? err.message : String(err)}`);
+            }
+            if (route === undefined)
+                continue;
+            const pattern = routePattern(route);
+            const other = byPattern.get(pattern);
+            if (other !== undefined)
+                throw new KestrelBootError(CORE, `http triggers for pipelines "${other}" and "${t.pipeline}" both resolve to "${pattern}"`);
+            byPattern.set(pattern, t.pipeline);
+            routes.push(route);
+        }
+        for (const [name, pipeline] of pipelines) {
+            checkDataflow(pipeline, routes.filter((r) => r.pipeline === name), crons.some((c) => c.pipeline === name), events.some((e) => e.pipeline === name));
+        }
+        const eventHooks = ordered.filter((mod) => mod.triggers?.event !== undefined);
+        if (eventHooks.length > 1)
+            throw new KestrelBootError(CORE, `modules "${eventHooks[0]?.name ?? ""}" and "${eventHooks[1]?.name ?? ""}" both provide an event trigger hook`);
+        if (events.length > 0 && eventHooks.length === 0)
+            throw new KestrelBootError(CORE, "event triggers need a module that provides an event trigger hook");
+        const eventHook = eventHooks[0];
+        const runs = createRunTracker();
+        const run = (name, ctxInput) => {
+            const pipeline = pipelines.get(name);
+            if (!pipeline)
+                throw new Error(`unknown pipeline "${name}"`);
+            return runs.track(() => runPipeline(pipeline, ctxInput, logger, { validateInput: dev }));
+        };
+        let server;
+        const stoppers = [];
+        let torndown = false;
+        return {
+            config,
+            contracts,
+            steps,
+            pipelines,
+            triggers: { http: routes, events, crons },
+            run,
+            async start() {
+                const started = {};
+                if (events.length > 0 && eventHook?.triggers?.event)
+                    stoppers.push(eventHook.triggers.event(instances.get(eventHook), events, run, logger));
+                if (crons.length > 0)
+                    stoppers.push(startCron(crons, run, logger));
+                const http = config.http;
+                if (http !== null) {
+                    server = createHttpServer(routes, run, logger, {
+                        maxBodyBytes: http.maxBodyBytes,
+                        trustProxy: http.trustProxy,
+                        healthPath: http.healthPath,
+                        inlineTypes: http.inlineTypes,
+                        timeouts: http.timeouts,
+                        ...(http.corsOrigin === undefined ? {} : { corsOrigin: http.corsOrigin }),
+                    });
+                    started.http = await listen(server, http.port, http.host);
+                    logger.info(`http listening on ${started.http.address}:${started.http.port}`, { routes: routes.length });
+                }
+                return started;
+            },
+            async stop(options = {}) {
+                const deadline = Date.now() + (options.timeoutMs ?? config.shutdownTimeoutMs);
+                let httpError;
+                const s = server;
+                server = undefined;
+                let closing;
+                if (s) {
+                    closing = new Promise((resolve, reject) => s.close((err) => (err ? reject(err) : resolve()))).catch((err) => {
+                        httpError = err instanceof Error ? err : new Error(String(err));
+                    });
+                }
+                let drained = await runs.drain(deadline - Date.now());
+                if (s && closing) {
+                    drained = (await drainConnections(s, closing, deadline)) && drained;
+                    s.closeAllConnections();
+                    await closing;
+                }
+                for (const stop of stoppers.splice(0))
+                    stop();
+                if (!torndown) {
+                    torndown = true;
+                    await teardownAll(ordered, instances, logger);
+                }
+                if (httpError)
+                    throw httpError;
+                return { drained };
+            },
+        };
+    }
+    catch (err) {
+        await teardownAll(ordered, instances, logger);
+        throw err;
+    }
+}

package/dist/cast.d.ts

@@ -0,0 +1,3 @@
+export type Boundary = "json" | "ast" | "dom" | "host";
+/** The only sanctioned double cast. `boundary` says which untyped source the value came from. */
+export declare function boundaryCast<T>(value: unknown, boundary: Boundary): T;

package/dist/cast.js

@@ -0,0 +1,6 @@
+/** The only sanctioned double cast. `boundary` says which untyped source the value came from. */
+export function boundaryCast(value, boundary) {
+    void boundary;
+    // eslint-disable-next-line no-restricted-syntax, @typescript-eslint/no-unnecessary-type-assertion
+    return value;
+}

package/dist/catalogue.d.ts

@@ -0,0 +1,11 @@
+import type { StepFactory, StepMap } from "./context.ts";
+import type { ModuleDefinition } from "./defineModule.ts";
+type Prefix<N extends string> = N extends `${infer P}/${string}` ? P : never;
+type StepNamesOf<P extends string, T extends StepMap> = {
+    [K in keyof T & string]: T[K] extends StepFactory ? `${P}.${K}:${string}` : `${P}.${K}`;
+}[keyof T & string];
+/** Every step name a module registers, factories with their `:arg` tail. */
+export type StepsOf<M> = M extends ModuleDefinition<infer N, infer T> ? StepNamesOf<Prefix<N>, T> : never;
+/** The union for a loaded module list — the `modules` array a consumer hands to `boot()`. */
+export type StepCatalogue<Ms extends readonly ModuleDefinition[]> = StepsOf<Ms[number]>;
+export {};

package/dist/catalogue.js

@@ -0,0 +1 @@
+export {};

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env -S node --disable-warning=ExperimentalWarning
+export {};

package/dist/cli.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env -S node --disable-warning=ExperimentalWarning
+import { resolve } from "node:path";
+import { boot } from "./boot.js";
+import { boundaryCast } from "./cast.js";
+import { KestrelBootError } from "./errors.js";
+import { loadConfig, loadModules, loadPipelines } from "./load.js";
+import { consoleLogger } from "./logger.js";
+const root = process.cwd();
+const FATAL_TIMEOUT_MS = 5_000;
+const FATAL_HANDLERS = Symbol.for("kestrel.fatalHandlers");
+function installFatalHandlers(kestrel) {
+    const installed = boundaryCast(process, "host");
+    if (installed[FATAL_HANDLERS])
+        return;
+    installed[FATAL_HANDLERS] = true;
+    const fatal = (event) => (reason) => {
+        const error = reason instanceof Error ? reason : new Error(String(reason));
+        consoleLogger.error(event, { reason: error.message, stack: error.stack ?? null });
+        const exit = () => process.exit(1);
+        void kestrel.stop({ timeoutMs: FATAL_TIMEOUT_MS }).then(exit, exit);
+    };
+    process.on("unhandledRejection", fatal("unhandledRejection"));
+    process.on("uncaughtException", fatal("uncaughtException"));
+}
+try {
+    const config = await loadConfig(resolve(root, "kestrel.config.ts"));
+    const modules = await loadModules(root, config);
+    const pipelines = await loadPipelines(root, config.pipelinesDir ?? "./pipelines");
+    const kestrel = await boot({ config, modules, pipelines, logger: consoleLogger, root });
+    await kestrel.start();
+    consoleLogger.info("kestrel started", { modules: modules.length, pipelines: kestrel.pipelines.size, triggers: kestrel.config.triggers.length });
+    installFatalHandlers(kestrel);
+    const shutdown = (signal) => () => {
+        consoleLogger.info("kestrel stopping", { signal });
+        void kestrel.stop().then(({ drained }) => {
+            if (!drained)
+                consoleLogger.error("shutdown deadline hit, closing anyway", { signal });
+            process.exit(drained ? 0 : 1);
+        }, (err) => {
+            consoleLogger.error("shutdown failed", { signal, error: err instanceof Error ? (err.stack ?? err.message) : String(err) });
+            process.exit(1);
+        });
+    };
+    process.once("SIGINT", shutdown("SIGINT"));
+    process.once("SIGTERM", shutdown("SIGTERM"));
+}
+catch (err) {
+    if (err instanceof KestrelBootError) {
+        consoleLogger.error("boot failed", { module: err.module, reason: err.reason });
+    }
+    else {
+        consoleLogger.error("boot failed", { error: err instanceof Error ? (err.stack ?? err.message) : String(err) });
+    }
+    process.exit(1);
+}