@valentinkolb/cloud 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valentinkolb/cloud",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Modular Hono+SolidJS framework for building per-app docker services behind a dynamic gateway. Powers cloud.stuve-ulm.de.",
   "license": "MIT",
   "repository": {
@@ -19,37 +19,49 @@
   "exports": {
     ".": "./src/index.ts",
     "./ui": "./src/ui/index.ts",
+    "./ui/styles.css": "./src/styles/global.css",
+    "./desktop": "./src/desktop/index.ts",
+    "./desktop/solid": "./src/desktop/solid.tsx",
     "./server": "./src/server/index.ts",
     "./browser": "./src/server/api-client.ts",
     "./shared": "./src/shared/index.ts",
     "./services": "./src/services/index.ts",
+    "./services/ipa/service-account": null,
     "./services/*": "./src/services/*",
     "./ssr": "./src/ssr/index.ts",
     "./ssr/islands": "./src/ssr/islands/index.ts",
     "./config": "./src/config/index.ts",
     "./config/*": "./src/config/*",
     "./contracts": "./src/contracts/index.ts",
+    "./api": "./src/api/index.ts",
+    "./clients/core": "./src/clients/core.ts",
     "./styles/global.css": "./src/styles/global.css"
   },
   "scripts": {
+    "test": "bun test",
     "typecheck": "node ../../node_modules/typescript/bin/tsc -p tsconfig.typecheck.json --noEmit --pretty false 2>&1 | grep -v node_modules | (! grep -q 'error TS')"
   },
   "dependencies": {
-    "@fontsource-variable/jetbrains-mono": "^5.2.8",
+    "@fontsource/ibm-plex-mono": "^5.2.7",
+    "@fontsource/ibm-plex-sans": "^5.2.8",
+    "@fontsource/ibm-plex-sans-condensed": "^5.2.8",
+    "@simplewebauthn/server": "^13.3.1",
     "@tabler/icons-webfont": "^3.36.1",
     "@tailwindcss/typography": "^0.5.19",
-    "@valentinkolb/ssr": "0.9.0",
-    "@valentinkolb/stdlib": "0.3.0",
+    "@valentinkolb/ssr": "0.10.0",
+    "@valentinkolb/stdlib": "0.12.0",
     "@valentinkolb/sync": "^5.0.0",
     "bun-plugin-tailwind": "^0.1.2",
     "hono": "^4.11.1",
     "hono-openapi": "^1.1.2",
+    "jose": "^6.1.3",
     "katex": "^0.16.28",
     "marked": "^17.0.1",
     "mermaid": "^11.12.2",
     "mustache": "^4.2.0",
-    "nodemailer": "^7.0.12",
-    "sanitize-html": "^2.17.0",
+    "nodemailer": "^8.0.10",
+    "sanitize-html": "^2.17.4",
+    "seroval": "^1.5.4",
     "solid-js": "^1.9.10",
     "tailwindcss": "^4.1.18",
     "zod": "^4.3.4"

package/scripts/preload.ts

@@ -7,10 +7,11 @@
  * uses /app as projectRoot → auto-detect scans all packages → all classes generated.
  * No @source directives needed in CSS files.
  */
-import tailwind from "bun-plugin-tailwind";
+import { existsSync, watch } from "node:fs";
 import { cp, mkdir } from "node:fs/promises";
-import { resolve, dirname } from "node:path";
+import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import tailwind from "bun-plugin-tailwind";
 
 const appId = process.env.APP_ID ?? "core";
 const { plugin } = await import(`../../${appId}/src/config`);
@@ -21,8 +22,7 @@ const workspaceRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../../..
 const publicDir = resolve(workspaceRoot, "public");
 await mkdir(publicDir, { recursive: true });
 
-// global.css + branding are only served by core (Traefik routes them there)
-if (appId === "core") {
+const buildGlobalCss = async () => {
   // Use styles.css at workspace root as entrypoint so the oxide scanner
   // walks up to /app/package.json and scans ALL packages for utility classes.
   // (If the CSS file is inside packages/lib/, it only scans packages/lib/.)
@@ -32,24 +32,74 @@ if (appId === "core") {
     naming: "global.css",
     plugins: [tailwind],
   });
+};
+
+const buildAppCss = async () => {
+  // `naming: "app.css"` is essential — without it, Bun.build with `root: workspaceRoot`
+  // preserves the directory structure (packages/<id>/src/styles/app.css) inside outdir,
+  // so Layout's `<link href="/public/<id>/app.css">` 404s and only global.css's classes
+  // reach the browser. That's why responsive grid utilities went missing on dashboard.
+  await Bun.build({
+    entrypoints: [resolve(workspaceRoot, `packages/${appId}/src/styles/app.css`)],
+    outdir: resolve(publicDir, appId),
+    naming: "app.css",
+    root: workspaceRoot, // same: auto-detect from /app
+    plugins: [tailwind],
+  });
+};
+
+const watchDevCss = (label: string, paths: string[], build: () => Promise<void>) => {
+  if (process.env.NODE_ENV !== "development") return;
+
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let running = false;
+  let queued = false;
+
+  const rebuild = () => {
+    if (running) {
+      queued = true;
+      return;
+    }
+
+    running = true;
+    void build()
+      .then(() => console.log(`[preload] rebuilt ${label}`))
+      .catch((error) => console.error(`[preload] failed to rebuild ${label}`, error))
+      .finally(() => {
+        running = false;
+        if (queued) {
+          queued = false;
+          rebuild();
+        }
+      });
+  };
+
+  const schedule = () => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(rebuild, 75);
+  };
+
+  for (const path of paths) {
+    if (!existsSync(path)) continue;
+    watch(path, { persistent: true }, schedule);
+  }
+};
+
+// global.css + branding are only served by core (Traefik routes them there)
+if (appId === "core") {
+  await buildGlobalCss();
 
   // Default branding asset: copy the tracked logo.svg into the runtime
   // public dir so serveBranding can fall back to it when no admin-uploaded
   // logo (data URI) is configured. User uploads are stored as base64 data
   // URIs in settings — no image processing (sharp etc.) needed.
-  await cp(
-    resolve(workspaceRoot, "packages/cloud/public/logo.svg"),
-    resolve(publicDir, "logo.svg"),
-  );
+  await cp(resolve(workspaceRoot, "packages/cloud/public/logo.svg"), resolve(publicDir, "logo.svg"));
 }
 
 // katex.css is only needed by notebooks (served by core via Traefik /public/katex.css)
 if (appId === "notebooks") {
   try {
-    await cp(
-      resolve(workspaceRoot, "node_modules/katex/dist/katex.min.css"),
-      resolve(publicDir, "katex.css"),
-    );
+    await cp(resolve(workspaceRoot, "node_modules/katex/dist/katex.min.css"), resolve(publicDir, "katex.css"));
   } catch {
     console.warn("[preload] katex.css not found, skipping");
   }
@@ -60,14 +110,19 @@ const appCssPath = resolve(workspaceRoot, `packages/${appId}/src/styles/app.css`
 const appPublicDir = resolve(publicDir, appId);
 await mkdir(appPublicDir, { recursive: true });
 
-// `naming: "app.css"` is essential — without it, Bun.build with `root: workspaceRoot`
-// preserves the directory structure (packages/<id>/src/styles/app.css) inside outdir,
-// so Layout's `<link href="/public/<id>/app.css">` 404s and only global.css's classes
-// reach the browser. That's why responsive grid utilities went missing on dashboard.
-await Bun.build({
-  entrypoints: [appCssPath],
-  outdir: appPublicDir,
-  naming: "app.css",
-  root: workspaceRoot, // same: auto-detect from /app
-  plugins: [tailwind],
-});
+await buildAppCss();
+
+watchDevCss("app.css", [resolve(appCssPath, "..")], buildAppCss);
+if (appId === "core") {
+  watchDevCss("global.css", [resolve(workspaceRoot, "styles.css"), resolve(workspaceRoot, "packages/cloud/src/styles")], buildGlobalCss);
+}
+
+// Optional app-owned dev assets. Production builds already have
+// scripts/build-extras.ts; this mirrors that hook for watch mode without
+// forcing app-specific asset logic into the framework preload.
+const devExtras = resolve(workspaceRoot, `packages/${appId}/scripts/dev-extras.ts`);
+if (existsSync(devExtras)) {
+  process.env.WORKSPACE_ROOT = workspaceRoot;
+  process.env.PUBLIC_DIR = publicDir;
+  await import(devExtras);
+}

package/src/_internal/define-app.ts

@@ -4,27 +4,23 @@
  * Merges SSR config, app meta, and server bootstrap into one call.
  * Returns `{ ssr, plugin, config, meta, start }`.
  */
+
+import type { SsrConfig } from "@valentinkolb/ssr";
 import { createConfig as createSsrConfig } from "@valentinkolb/ssr";
 import { createSSRHandler, routes } from "@valentinkolb/ssr/hono";
 import { Hono } from "hono";
 import { serveStatic } from "hono/bun";
 import { generateSpecs } from "hono-openapi";
-import type { SsrConfig } from "@valentinkolb/ssr";
-import type {
-  AppMeta,
-  AppLifecycle,
-  AppCapabilities,
-  AppSearchContext,
-  CloudContext,
-} from "../contracts/app";
+import type { AppCapabilities, AppLifecycle, AppMeta, AppSearchContext, CloudContext } from "../contracts/app";
 import type { AppRegistryEntry } from "../contracts/registry";
-import type { Role } from "../contracts/shared";
 import type { AppSettingsMap, KindToType } from "../contracts/settings-types";
-import { createSettingsAPI, type SettingsAPI } from "../services/settings/api";
-import { registerSettings, type SettingDef } from "../services/settings/defaults";
+import type { Role } from "../contracts/shared";
+import { themeBootstrapScript } from "../shared/theme";
 import { auth } from "../server/middleware/auth";
 import { logger } from "../services/logging";
-import { get, set, loadCache as loadSettingsCache } from "../services/settings";
+import { get, loadCache as loadSettingsCache, set } from "../services/settings";
+import { createSettingsAPI, type SettingsAPI } from "../services/settings/api";
+import { registerSettings, type SettingDef } from "../services/settings/defaults";
 import { createHeartbeat } from "./heartbeat";
 import { ensureRuntimeWatcher, getCurrentRuntime, stopRuntimeWatcher } from "./runtime-watcher";
 
@@ -81,7 +77,7 @@ export type AppOptions<S extends AppSettingsMap = {}> = {
   /**
    * Legal/info links contributed by this app — aggregated app-wide via
    * `listLegalLinks()` and rendered in login footer, app Footer, rail more
-   * dropdown. Each app contributes its own (e.g. settings owns
+   * dropdown. Each app contributes its own (e.g. core owns
    * Imprint/Privacy/Terms; faq owns FAQ). KISS: no `external` flag, links
    * always open in a new tab from the login footer.
    */
@@ -102,8 +98,8 @@ export type AppOptions<S extends AppSettingsMap = {}> = {
    *   `/admin/<id>`   — admin SSR pages
    *   `/public/<id>`  — built CSS and other static assets
    *
-   * Apps with non-standard URLs (core's `/auth`, `/me`; oauth's `/oauth`,
-   * `/.well-known/...`; settings' `/legal/*`, `/impressum`) list whatever
+   * Apps with non-standard URLs (core's `/auth`, `/me`, `/legal/*`, `/impressum`;
+   * oauth's `/oauth`, `/.well-known/...`) list whatever
    * top-level paths they own. The gateway is dumb — it just builds a
    * prefix-trie from these strings.
    */
@@ -151,7 +147,7 @@ export type StartOptions = {
    * before this fetch — they take precedence over any catch-all the app
    * might register.
    */
-  fetch: (req: Request) => Response | Promise<Response>;
+  fetch: (req: Request, env?: unknown) => Response | Promise<Response>;
   /**
    * Hono router to scan for OpenAPI route metadata. When set together with
    * `defineApp({ openapi: "..." })`, the framework generates an OpenAPI
@@ -172,6 +168,7 @@ export type StartOptions = {
 
 export type StartResult = {
   port: number;
+  development: boolean;
   fetch: Hono["fetch"];
 };
 
@@ -204,6 +201,8 @@ export type AppDefinition<S extends AppSettingsMap = {}> = {
 // ── Implementation ──────────────────────────────────────────────────────────
 
 export const defineApp = <const S extends AppSettingsMap = {}>(opts: AppOptions<S>): AppDefinition<S> => {
+  const isDevelopment = process.env.NODE_ENV === "development";
+
   // ── 0. Register declared settings into the runtime registry ──────────
   // SETTINGS_MAP is the single source of truth for validation in store.ts
   // (writeKey checks SETTINGS_MAP.get(key)) and for snapshot.ts (allKnownKeys
@@ -237,7 +236,7 @@ export const defineApp = <const S extends AppSettingsMap = {}>(opts: AppOptions<
 
   // ── 1. SSR config ─────────────────────────────────────────────────────
   const { config, plugin, html } = createSsrConfig<PageOptions>({
-    dev: process.env.NODE_ENV !== "production",
+    dev: isDevelopment,
     verbose: true,
     rootDir: opts.appRoot ?? process.cwd(),
     basePath: opts.basePath,
@@ -252,17 +251,10 @@ export const defineApp = <const S extends AppSettingsMap = {}>(opts: AppOptions<
     <meta name="theme-color" content="#09090b">
     <meta name="mobile-web-app-capable" content="yes">
     <link rel="icon" href="/branding/favicon">
-    <link rel="stylesheet" href="/public/global.css?v=${v}">
+    <style data-cloud-css-layers>@layer theme, base, components, utilities;</style>
     <link rel="stylesheet" href="/public/${opts.id}/app.css?v=${v}">
-    <script>
-      (function() {
-        var el = document.documentElement;
-        if (!el.hasAttribute('data-theme-fixed')) {
-          var theme = document.cookie.match(/theme=([^;]+)/)?.[1] || 'light';
-          el.classList.add(theme);
-        }
-      })();
-    </script>
+    <link rel="stylesheet" href="/public/global.css?v=${v}">
+    <script>${themeBootstrapScript}</script>
   </head>
   <body>
     ${body}
@@ -288,6 +280,7 @@ export const defineApp = <const S extends AppSettingsMap = {}>(opts: AppOptions<
     nav: opts.nav,
     legalLinks: opts.legalLinks ? [...opts.legalLinks] : undefined,
     widgets: opts.widgets ? opts.widgets.map((w) => ({ ...w })) : undefined,
+    settingKeys: opts.settings ? Object.keys(opts.settings) : undefined,
     openapi: opts.openapi,
   };
 
@@ -310,16 +303,17 @@ export const defineApp = <const S extends AppSettingsMap = {}>(opts: AppOptions<
       description: meta.description,
       baseUrl,
       routes: [...meta.routes],
-      nav: (meta.nav || meta.adminHref)
-        ? {
-            href: meta.nav?.href ?? "",
-            match: meta.nav?.match,
-            section: meta.nav?.section ?? "hidden",
-            requiresAuth: meta.nav?.requiresAuth,
-            requiresRoles: meta.nav?.requiresRoles,
-            adminHref: meta.adminHref,
-          }
-        : undefined,
+      nav:
+        meta.nav || meta.adminHref
+          ? {
+              href: meta.nav?.href ?? "",
+              match: meta.nav?.match,
+              section: meta.nav?.section ?? "hidden",
+              requiresAuth: meta.nav?.requiresAuth,
+              requiresRoles: meta.nav?.requiresRoles,
+              adminHref: meta.adminHref,
+            }
+          : undefined,
       search: startOpts.capabilities?.search
         ? {
             tags: [...(startOpts.capabilities.search.tags ?? [])],
@@ -330,6 +324,7 @@ export const defineApp = <const S extends AppSettingsMap = {}>(opts: AppOptions<
         : undefined,
       legalLinks: meta.legalLinks ? meta.legalLinks.map((l) => ({ ...l })) : undefined,
       widgets: meta.widgets ? meta.widgets.map((w) => ({ ...w })) : undefined,
+      settingKeys: meta.settingKeys ? [...meta.settingKeys] : undefined,
       openapi: advertiseOpenapi ? opts.openapi : undefined,
     };
 
@@ -354,12 +349,15 @@ export const defineApp = <const S extends AppSettingsMap = {}>(opts: AppOptions<
 
     const server = new Hono()
       .route(ssrMountPath, routes(config))
-      .use("/public/*", serveStatic({
-        root: "./",
-        onFound: (_path, c) => {
-          c.header("Cache-Control", "public, max-age=31536000, immutable");
-        },
-      }))
+      .use(
+        "/public/*",
+        serveStatic({
+          root: "./",
+          onFound: (_path, c) => {
+            c.header("Cache-Control", isDevelopment ? "no-store" : "public, max-age=31536000, immutable");
+          },
+        }),
+      )
       // serveStatic calls next() on miss — terminate /public/* here so a
       // missing asset is a clean 404 instead of falling through to the app
       // fetch (which might render an HTML page for the missing path).
@@ -368,6 +366,9 @@ export const defineApp = <const S extends AppSettingsMap = {}>(opts: AppOptions<
     if (startOpts.capabilities?.search) {
       const searchRun = startOpts.capabilities.search.run;
       server.post("/api/_internal/search", auth.requireRole("authenticated"), async (c) => {
+        if (!c.get("user")) {
+          return c.json({ message: "Search providers require a user-backed actor", code: "FORBIDDEN" }, 403);
+        }
         const body = await c.req.json<{ query: string; tags: string[]; limit: number }>();
         const ctx: AppSearchContext = { get: (key) => c.get(key) as never };
         const results = await searchRun({ query: body.query, tags: body.tags, limit: body.limit, ctx });
@@ -404,7 +405,11 @@ export const defineApp = <const S extends AppSettingsMap = {}>(opts: AppOptions<
     // User's fetch handles everything else. The framework doesn't inject any
     // context vars here — the user's router is expected to register the
     // middlewares it needs (middleware.runtime, middleware.settings, …).
-    server.all("*", (c) => Promise.resolve(startOpts.fetch(c.req.raw)));
+    //
+    // env is threaded through so Bun-specific helpers inside the user's
+    // router still work — most importantly `upgradeWebSocket` from hono/bun,
+    // which reads the Bun server off `c.env`.
+    server.all("*", (c) => Promise.resolve(startOpts.fetch(c.req.raw, c.env)));
 
     // Lifecycle
     const cloudCtx: CloudContext = {
@@ -431,7 +436,9 @@ export const defineApp = <const S extends AppSettingsMap = {}>(opts: AppOptions<
       if (stopping) return;
       stopping = true;
       log.info(`Stopping: ${meta.id}`);
-      try { if (startOpts.lifecycle?.stop) await startOpts.lifecycle.stop(cloudCtx); } catch {}
+      try {
+        if (startOpts.lifecycle?.stop) await startOpts.lifecycle.stop(cloudCtx);
+      } catch {}
       await stopRuntimeWatcher();
       await heartbeat.stop();
     };
@@ -439,7 +446,7 @@ export const defineApp = <const S extends AppSettingsMap = {}>(opts: AppOptions<
     process.on("SIGTERM", () => void shutdown().then(() => process.exit(0)));
     process.on("SIGINT", () => void shutdown().then(() => process.exit(0)));
 
-    return { port, fetch: server.fetch };
+    return { port, development: isDevelopment, fetch: server.fetch };
   };
 
   return {

package/src/api/accounts-entities.ts

@@ -32,6 +32,7 @@ const QuerySchema = z
     profile: UserProfileSchema.optional(),
     exclude_user_ids: z.string().optional(),
     exclude_group_ids: z.string().optional(),
+    exclude_service_account_ids: z.string().optional(),
     user_member_of_group_ids: z.string().optional(),
     member_of_group_id: z.uuid().optional(),
     manager_of_group_id: z.uuid().optional(),
@@ -102,6 +103,8 @@ const app = new Hono()
       if (!excludeUserIds.ok) return respond(c, fail(err.badInput(excludeUserIds.message)));
       const excludeGroupIds = parseUuidList(query.exclude_group_ids, "exclude_group_ids");
       if (!excludeGroupIds.ok) return respond(c, fail(err.badInput(excludeGroupIds.message)));
+      const excludeServiceAccountIds = parseUuidList(query.exclude_service_account_ids, "exclude_service_account_ids");
+      if (!excludeServiceAccountIds.ok) return respond(c, fail(err.badInput(excludeServiceAccountIds.message)));
       const userMemberOfGroupIds = parseUuidList(query.user_member_of_group_ids, "user_member_of_group_ids");
       if (!userMemberOfGroupIds.ok) return respond(c, fail(err.badInput(userMemberOfGroupIds.message)));
 
@@ -113,6 +116,7 @@ const app = new Hono()
         profile: query.profile,
         excludeUserIds: excludeUserIds.value,
         excludeGroupIds: excludeGroupIds.value,
+        excludeServiceAccountIds: excludeServiceAccountIds.value,
         userMemberOfGroupIds: userMemberOfGroupIds.value,
         memberOfGroupId: query.member_of_group_id,
         managerOfGroupId: query.manager_of_group_id,

package/src/api/admin-core-settings.ts

@@ -0,0 +1,98 @@
+/**
+ * Admin API for platform-wide runtime settings.
+ *
+ * This route lives in cloud-lib because `/admin/settings` is a platform page
+ * and needs a typed client without depending on the core app package. The
+ * core app mounts it under `/api/admin/core/settings`.
+ */
+import { sql } from "bun";
+import { Hono } from "hono";
+import { z } from "zod";
+import { listApps } from "../_internal/registry";
+import { auth, v, type AuthContext } from "../server";
+import { settingsDeleteLegacyKeys, settingsListLegacyKeys } from "../services";
+import * as settings from "../services/settings";
+import { SETTINGS_MAP } from "../services/settings/defaults";
+
+const BulkUpdateSchema = z.record(z.string(), z.unknown());
+
+type FieldErrors = Record<string, string>;
+
+const isKnownSetting = (key: string): boolean => SETTINGS_MAP.has(key);
+const liveSettingKeys = async () => (await listApps()).flatMap((app) => [...(app.settingKeys ?? [])]);
+
+const app = new Hono<AuthContext>()
+  .get("/legacy", auth.requireRole("admin"), async (c) => {
+    return c.json(await settingsListLegacyKeys(await liveSettingKeys()));
+  })
+  .delete("/legacy", auth.requireRole("admin"), async (c) => {
+    return c.json(await settingsDeleteLegacyKeys(await liveSettingKeys()));
+  })
+  .put(
+    "/",
+    auth.requireRole("admin"),
+    v("json", BulkUpdateSchema),
+    async (c) => {
+      const updates = c.req.valid("json");
+      const keys = Object.keys(updates);
+
+      if (keys.length === 0) {
+        return c.body(null, 204);
+      }
+
+      const ownership: FieldErrors = {};
+      for (const key of keys) {
+        if (!isKnownSetting(key)) {
+          ownership[key] = `Unknown setting "${key}"`;
+        }
+      }
+      if (Object.keys(ownership).length > 0) {
+        return c.json({ message: "Invalid keys", errors: ownership }, 400);
+      }
+
+      const fieldErrors: FieldErrors = {};
+      try {
+        await sql.begin(async () => {
+          for (const [key, value] of Object.entries(updates)) {
+            try {
+              await settings.set(key, value);
+            } catch (error) {
+              fieldErrors[key] = error instanceof Error ? error.message : `Failed to update ${key}`;
+              throw error;
+            }
+          }
+        });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Save failed";
+        return c.json(
+          {
+            message,
+            errors: Object.keys(fieldErrors).length > 0 ? fieldErrors : { _form: message },
+          },
+          400,
+        );
+      }
+
+      return c.body(null, 204);
+    },
+  )
+  .delete(
+    "/:key{.+}",
+    auth.requireRole("admin"),
+    async (c) => {
+      const key = c.req.param("key");
+      if (!isKnownSetting(key)) {
+        return c.json({ message: `Unknown setting "${key}"` }, 400);
+      }
+      try {
+        await settings.remove(key);
+        return c.body(null, 204);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Reset failed";
+        return c.json({ message }, 500);
+      }
+    },
+  );
+
+export default app;
+export type ApiType = typeof app;

package/src/api/announcements.ts

@@ -0,0 +1,131 @@
+import { ok } from "@valentinkolb/stdlib";
+import { Hono } from "hono";
+import { describeRoute } from "hono-openapi";
+import { z } from "zod";
+import {
+  ActiveAnnouncementsResponseSchema,
+  AnnouncementEntrySchema,
+  AnnouncementListResponseSchema,
+  CreateAnnouncementSchema,
+  ErrorResponseSchema,
+  MessageResponseSchema,
+  parseAnnouncementCookieHeader,
+  UpdateAnnouncementSchema,
+} from "../contracts";
+import { type AuthContext, auth, jsonResponse, requiresAdmin, requiresAuth, respond, v } from "../server";
+import { announcements } from "../services";
+
+const IdParamSchema = z.object({ id: z.uuid() });
+
+const withMessage = async <T>(operation: Promise<import("@valentinkolb/stdlib").Result<T>>, message: string) => {
+  const result = await operation;
+  if (!result.ok) return result;
+  return ok({ message });
+};
+
+export const announcementRoutes = new Hono<AuthContext>().get(
+  "/active",
+  auth.requireRole("authenticated"),
+  describeRoute({
+    tags: ["Announcements"],
+    summary: "List active user announcements",
+    description: "Returns active banners and unseen announcements for the current request cookie state.",
+    ...requiresAuth,
+    responses: {
+      200: jsonResponse(ActiveAnnouncementsResponseSchema, "Active announcements"),
+      401: jsonResponse(ErrorResponseSchema, "Authentication required"),
+    },
+  }),
+  async (c) => {
+    const state = parseAnnouncementCookieHeader(c.req.header("Cookie"));
+    return respond(c, ok(await announcements.active.forState({ state })));
+  },
+);
+
+export const adminAnnouncementRoutes = new Hono<AuthContext>()
+  .use(auth.requireRole("admin"))
+  .get(
+    "/",
+    describeRoute({
+      tags: ["Admin Announcements"],
+      summary: "List announcements",
+      ...requiresAdmin,
+      responses: {
+        200: jsonResponse(AnnouncementListResponseSchema, "Announcements"),
+        401: jsonResponse(ErrorResponseSchema, "Authentication required"),
+        403: jsonResponse(ErrorResponseSchema, "Admin access required"),
+      },
+    }),
+    v(
+      "query",
+      z.object({
+        kind: z.enum(["announcement", "banner"]).optional(),
+        search: z.string().optional(),
+      }),
+    ),
+    async (c) => {
+      const query = c.req.valid("query");
+      const items = await announcements.admin.list({
+        filter: { kind: query.kind, query: query.search },
+      });
+      return respond(c, ok({ items }));
+    },
+  )
+  .post(
+    "/",
+    describeRoute({
+      tags: ["Admin Announcements"],
+      summary: "Create announcement",
+      ...requiresAdmin,
+      responses: {
+        201: jsonResponse(AnnouncementEntrySchema, "Created announcement"),
+        400: jsonResponse(ErrorResponseSchema, "Validation error"),
+        401: jsonResponse(ErrorResponseSchema, "Authentication required"),
+        403: jsonResponse(ErrorResponseSchema, "Admin access required"),
+      },
+    }),
+    v("json", CreateAnnouncementSchema),
+    async (c) => respond(c, announcements.admin.create({ data: c.req.valid("json"), actorId: c.get("user").id }), 201),
+  )
+  .patch(
+    "/:id",
+    describeRoute({
+      tags: ["Admin Announcements"],
+      summary: "Update announcement",
+      ...requiresAdmin,
+      responses: {
+        200: jsonResponse(AnnouncementEntrySchema, "Updated announcement"),
+        400: jsonResponse(ErrorResponseSchema, "Validation error"),
+        401: jsonResponse(ErrorResponseSchema, "Authentication required"),
+        403: jsonResponse(ErrorResponseSchema, "Admin access required"),
+        404: jsonResponse(ErrorResponseSchema, "Announcement not found"),
+      },
+    }),
+    v("param", IdParamSchema),
+    v("json", UpdateAnnouncementSchema),
+    async (c) =>
+      respond(
+        c,
+        announcements.admin.update({
+          id: c.req.valid("param").id,
+          data: c.req.valid("json"),
+          actorId: c.get("user").id,
+        }),
+      ),
+  )
+  .delete(
+    "/:id",
+    describeRoute({
+      tags: ["Admin Announcements"],
+      summary: "Delete announcement",
+      ...requiresAdmin,
+      responses: {
+        200: jsonResponse(MessageResponseSchema, "Announcement deleted"),
+        401: jsonResponse(ErrorResponseSchema, "Authentication required"),
+        403: jsonResponse(ErrorResponseSchema, "Admin access required"),
+        404: jsonResponse(ErrorResponseSchema, "Announcement not found"),
+      },
+    }),
+    v("param", IdParamSchema),
+    async (c) => respond(c, withMessage(announcements.admin.remove({ id: c.req.valid("param").id }), "Announcement deleted.")),
+  );