/// <reference types="bun-types" preserve="true" />
import { type AuthRoutesConfig, type ExtraRouteDefinition } from "@cosmicdrift/kumiko-framework/api";
import { type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
import type { ErrorDocsConfig } from "@cosmicdrift/kumiko-framework/errors";
import { type TestStack, type TestStackOptions } from "@cosmicdrift/kumiko-framework/stack";
import { type PageHeadResolver, type PageHeadSystemQuery } from "@cosmicdrift/kumiko-headless/apex";
import { type SystemWireDeps } from "@cosmicdrift/kumiko-server-runtime/extra-routes-deps";
type BunServer = typeof Bun extends undefined ? unknown : ReturnType<typeof Bun.serve>;
/** Multi-entry mode for apps that ship several separate bundles (e.g.
 *  publicstatus: `admin.<base>` loads the admin UI, otherwise the public
 *  page).
 *
 *  kumiko-build reads the same entry list from package.json
 *  `kumiko.clientEntries` and serves `/client-<name>.js` per HTTP — the
 *  dev server and the prod build stay in sync via that shared declaration,
 *  not a filename convention. Mutually exclusive with `clientEntry`.
 *  Multi-entry apps MUST also set `hostDispatch` — otherwise the server
 *  has no way to know which HTML to serve. */
export type DevClientEntry = {
    /** Logical name. Should match the corresponding package.json
     *  `kumiko.clientEntries[].name` so dev and prod produce identical
     *  asset URLs (`/client-<name>.js`). */
    readonly name: string;
    /** Absoluter Pfad zur Browser-Entry-Datei. */
    readonly sourceFile: string;
    /** Optional eigenes HTML-Template für diesen Entry. Wenn nicht gesetzt,
     *  wird `htmlPath` (das default-Template) für alle Entries genutzt. */
    readonly htmlPath?: string;
};
/** Discriminated union, identical in shape to `runProdApp.hostDispatch`, so
 *  dev/prod routing mirrors 1:1 — an apex 404 in prod is an apex 404 in dev
 *  (with an `/etc/hosts` entry for the affected domain). HTML never carries
 *  a schema, in dev or prod — createKumikoApp fetches it itself from the
 *  authenticated GET /api/schema. */
export type DevHostDispatchResult = {
    readonly kind: "html";
    readonly entryName: string;
    /** @deprecated Ignored — HTML never carries the schema; createKumikoApp
     *  fetches it from the authenticated GET /api/schema. */
    readonly injectSchema?: boolean;
} | {
    /** Static HTML: serves a file verbatim, no bundle injection. Mirrors
     *  prod's `{ kind: "html", file: ... }` for marketing/apex pages that
     *  don't need React. Path relative to the server CWD. */
    readonly kind: "static-html";
    readonly file: string;
} | {
    readonly kind: "redirect";
    readonly to: string;
    readonly status?: 301 | 302;
} | {
    /** Plain 404 by default. `file` serves a static page with status 404
     *  (like `static-html`), `entryName` serves that bundle's shell with 404;
     *  `file` wins when both are set. */
    readonly kind: "not-found";
    readonly entryName?: string;
    readonly file?: string;
};
/** Picks an entry by inspecting the incoming request. Wird von
 *  Multi-Entry-Apps gesetzt; im Single-Entry-Mode irrelevant. */
export type DevHostDispatch = (req: Request, deps: {
    readonly systemQuery: PageHeadSystemQuery;
}) => DevHostDispatchResult | Promise<DevHostDispatchResult>;
export type CreateKumikoServerOptions = {
    /** Features whose entities, handlers, and screens get wired into the
     *  dev stack. Pass every feature the app is supposed to run. */
    readonly features: readonly FeatureDefinition[];
    /** Absolute path to the browser entry module. The dev-server runs
     *  `Bun.build` on it and serves the output at `/client.js`. Omit to
     *  run a headless API-only dev-stack (rare — every sample has one).
     *  Mutually exclusive mit `clientEntries`. */
    readonly clientEntry?: string;
    /** Multi-Entry-Mode: mehrere getrennte Bundles, jeweils unter
     *  `/client-<name>.js`. Mutually exclusive mit `clientEntry`. Setze
     *  `hostDispatch` mit, sonst bleibt unklar welches Template zurück-
     *  geht. */
    readonly clientEntries?: readonly DevClientEntry[];
    /** Multi-Entry-Mode: Routing pro Request. Inspiziert `Host` (oder
     *  was auch immer) und liefert eine Discriminated-Union zurück
     *  (html → entry-bundle, redirect → 30x, not-found → 404).
     *  Symmetric zu `runProdApp.hostDispatch` damit dev/prod-Drift
     *  beim Routing unmöglich ist. */
    readonly hostDispatch?: DevHostDispatch;
    /** @internal — ersetzt `Bun.build` für Tests. Default ruft die echte
     *  Bun-Toolchain. Tests unter Node injizieren einen Stub damit der
     *  Routing-Pfad treibbar bleibt ohne Bun.build aufzurufen.
     *  KEIN Public-API-Surface — präfixiert mit `_` damit Konsumenten
     *  wissen dass das ein Test-Seam ist. */
    readonly _buildBundle?: (sourceFile: string) => Promise<{
        readonly js: string;
        readonly map: string;
    }>;
    /** @internal — replaces the native directory watcher in tests. */
    readonly _watchDirectory?: DirectoryWatchEvents;
    /** Absolute path to the CSS entry (typically styles.css with
     *  @import "tailwindcss"). The dev-server builds it with the Tailwind
     *  CLI and serves the result at /styles.css; `stylesheetWatch` decides
     *  whether the CLI keeps running with `--watch` afterwards.
     *
     *  When `undefined` and a client entry is set, the app's own
     *  src/styles.css wins, otherwise `@cosmicdrift/kumiko-renderer-web/styles.css`
     *  resolves via package exports, so no sample hardcodes a monorepo-relative path.
     *
     *  `stylesheet: false` disables the CSS pipeline. */
    readonly stylesheet?: string | false;
    /** `true`: the Tailwind CLI keeps running with `--watch` after the
     *  initial build. `false`: CSS is built once at boot, no watcher.
     *  When `undefined`, env `KUMIKO_DEV_STYLESHEET_WATCH=0` means `false`,
     *  anything else `true`. `defineAppE2eConfig` sets that env: Tailwind v4
     *  subscribes to the whole app cwd without a gitignore filter, so every
     *  Playwright artifact write under test-results/ would trigger a rebuild. */
    readonly stylesheetWatch?: boolean;
    /** Optional HTML template served at `GET /`. The dev-server injects
     *  a `<script type="module" src="/client.js">` and a reload-listener
     *  snippet into `</body>` if those aren't already there. Defaults to a
     *  minimal empty-body document — enough to boot the client. */
    readonly htmlPath?: string;
    /** Port to listen on. Default 4173. Overridable via `PORT` env. */
    readonly port?: number;
    /** Extra directories to watch for reload triggers. The entry's
     *  directory is watched automatically. */
    readonly watchDirs?: readonly string[];
    /** When false, no SIGINT/SIGTERM handlers are installed. Tests set
     *  this so repeated `createKumikoServer` calls don't accumulate
     *  listeners on the process. Default true (dev-server behaviour). */
    readonly installSignalHandlers?: boolean;
    /** Auth-Route-Config (login, tenants, switch-tenant, logout). Wenn
     *  gesetzt wird die Auto-JWT-Mint auf GET / abgeschaltet — der
     *  Client ist dann selbst fürs Login zuständig. Zur echten Wirkung
     *  brauchen die dazugehörigen Features (user/tenant/auth-email-
     *  password) via `features` drin sein. */
    readonly auth?: AuthRoutesConfig;
    /** Extra-AppContext-Keys (z.B. configResolver für config-feature).
     *  Wird an setupTestStack weitergereicht. Siehe TestStackOptions
     *  für die erlaubten Shapes (object oder factory-function). */
    readonly extraContext?: TestStackOptions["extraContext"];
    /** Anonymous-Access aktivieren — Requests ohne JWT werden als
     *  Pseudo-User mit Rolle `anonymous` durchgelassen, sofern der
     *  Handler `roles: ["anonymous"]` deklariert. Tenant-Resolution per
     *  Header/Cookie/Default; siehe AnonymousAccessConfig. */
    readonly anonymousAccess?: TestStackOptions["anonymousAccess"];
    /** File-Storage-Provider — durchgereicht an setupTestStack. Wenn gesetzt,
     *  mountet der Stack die Upload-Routes (POST/GET/DELETE /api/files) +
     *  `ctx.files` und legt die file_refs-Tabelle an. Für Demos:
     *  `{ storageProvider: createInMemoryFileProvider() }`. */
    readonly files?: TestStackOptions["files"];
    /** Feature-toggle resolver — durchgereicht an setupTestStack. Wenn
     *  gesetzt, konsultiert der dispatcher-feature-gate, hook-filter, MSP-
     *  filter den callback; absent = alle features always-on. Erforderlich
     *  für Tier-Composition (Sprint 8) wo per-Tenant unterschiedliche
     *  features aktiv sein sollen. Die typische produktive Implementierung
     *  ist `() => globalFeatureToggleRuntime.effectiveFeatures` post-boot
     *  (createLateBoundHolder-pattern, weil runtime stack.db braucht). */
    readonly effectiveFeatures?: TestStackOptions["effectiveFeatures"];
    /** Wird nach dem Aufsetzen der Entity-Tabellen aufgerufen. Hook für
     *  non-entity-tables (unsafePushTables) und Seeding (admin user, initial
     *  tenant, …). Muss idempotent sein — im persistent-DB-Modus läuft
     *  es bei jedem Boot. */
    readonly onAfterSetup?: (stack: TestStack) => Promise<void>;
    /** Declarative HTTP-routes outside the /api/write|query|batch pipeline —
     *  symmetric to runProdApp.extraRoutes (kumiko-framework#3050). Mounted
     *  inside buildServer (setupTestStack), before the Static/HTML-fallback,
     *  so an own GET (/feed.xml, /og-image, …) wins over the dev-asset path. */
    readonly extraRoutes?: readonly ExtraRouteDefinition[];
    /** Forwarded to setupTestStack → buildServer's top-level
     *  `ServerOptions.trustedProxyHops`. Dev usually runs unproxied, so this
     *  is normally left unset (default 0). */
    readonly trustedProxyHops?: number;
    /** Links the app's own error reasons to its own docs (`docsUrl` in error responses); framework reasons keep the framework docs link. */
    readonly errorDocs?: ErrorDocsConfig;
    /** Hook for app-wired co-running components that need the system-write
     *  dispatcher — runs after buildServer, before onAfterSetup (seeds), with
     *  NO `app` (routes are declared via `extraRoutes`, not wired here). */
    readonly wire?: (deps: SystemWireDeps) => void | Promise<void>;
    /** Per-request head-metadata resolver (Open-Graph/title/description) —
     *  same option, same `PageHeadResolver` signature, and same shared
     *  resolve+inject call (`resolveAndInjectPageHead`) as `runProdApp`'s
     *  `resolvePageHead`, so dev and e2e exercise the exact code prod does
     *  (kumiko-framework#3026). Consulted for every templated HTML response
     *  (the default single-entry shell and a host-dispatched `"html"` entry),
     *  right before it's served. On error, `null`, or a timeout, the shell
     *  ships unchanged with status 200 — never a 500. `systemQuery` inside
     *  the resolver runs as the anonymous role, same as prod. */
    readonly resolvePageHead?: PageHeadResolver;
};
export type KumikoServerHandle = {
    /** The fetch handler that routes a Request through the dev-server
     *  layer (HTML, /client.js, /_reload, SSE) and falls back to the
     *  underlying Kumiko stack. Tests call this directly to exercise
     *  the routing without going through real sockets. */
    readonly fetch: (req: Request) => Promise<Response>;
    /** Bun.serve instance. `undefined` when running outside Bun (e.g.
     *  in vitest under Node) — the handle still works via `.fetch`. */
    readonly server: BunServer | undefined;
    readonly stack: TestStack;
    /** Stops the server and tears down the stack (DB + redis). */
    readonly stop: () => Promise<void>;
    /** BullMQ queue-name prefix of this boot: per-boot in ephemeral mode, so
     *  its `bull:<prefix>-*` keys belong to this server alone on a shared Redis. */
    readonly jobQueueNamePrefix: string;
};
export declare const STYLESHEET_WATCH_ENV = "KUMIKO_DEV_STYLESHEET_WATCH";
export declare const PROD_BUNDLES_ENV = "KUMIKO_DEV_PROD_BUNDLES";
export declare const DEFAULT_HTML = "<!doctype html>\n<html lang=\"en\">\n  <head>\n    <meta charset=\"utf-8\" />\n    <meta name=\"viewport\" content=\"width=device-width,initial-scale=1,interactive-widget=resizes-content\" />\n    <title>Kumiko</title>\n  </head>\n  <body>\n    <div id=\"root\"></div>\n    <script type=\"module\" src=\"/client.js\"></script>\n  </body>\n</html>\n";
type DirectoryWatchEvents = (dir: string, options: {
    readonly recursive: true;
    readonly signal: AbortSignal;
}) => AsyncIterable<{
    readonly filename: string | null;
}>;
export declare function classifyChange(filename: string): "restart" | "hot-reload" | "ignore";
export declare function classifyWatchedChange(watchedDir: string, filename: string, entrySourceFiles: ReadonlySet<string>): ReturnType<typeof classifyChange>;
export declare function resolveStylesheet(options: CreateKumikoServerOptions): string | undefined;
export declare function resolveStylesheetWatch(options: Pick<CreateKumikoServerOptions, "stylesheetWatch">, env?: Readonly<Record<string, string | undefined>>): boolean;
export declare function createKumikoServer(options: CreateKumikoServerOptions): Promise<KumikoServerHandle>;
export {};