@k2b/cloud 0.6.0-rc.0 → 0.7.0

package/README.md

@@ -78,9 +78,9 @@ A standard app declares four prefixes (`/api/<id>`, `/app/<id>`, `/admin/<id>`,
 
 ## Documentation
 
-Full walkthroughs, the per-app anatomy, deployment templates, and a reference app:
+Application setup, public contracts, and deployment guidance:
 
-- **[github.com/ValentinKolb/cloud-template](https://github.com/ValentinKolb/cloud-template)** — starter repo with a working reference app + the complete app-authoring guide
+- **[Create the first application](https://github.com/k2b-dev/cloud/blob/main/docs-site/docs/en/build/getting-started.md)** — standalone project setup and a verified API endpoint
 - **[github.com/k2b-dev/cloud](https://github.com/k2b-dev/cloud)** — the platform monorepo (gateway, core, all platform apps)
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/cloud",
-  "version": "0.6.0-rc.0",
+  "version": "0.7.0",
   "description": "Modular Hono+SolidJS framework for building per-app docker services behind a dynamic gateway. Powers cloud.stuve-ulm.de.",
   "license": "AGPL-3.0-or-later",
   "repository": {
@@ -16,7 +16,10 @@
     "scripts",
     "public",
     "!src/**/*.test.ts",
-    "!src/**/*.integration.test.ts"
+    "!src/**/*.test.tsx",
+    "!src/**/*.integration.test.ts",
+    "!scripts/**/*.test.ts",
+    "!scripts/runtime-recovery-*.ts"
   ],
   "exports": {
     ".": "./src/index.ts",
@@ -29,9 +32,13 @@
     "./browser/live": "./src/browser/live-websocket.ts",
     "./browser/notifications": "./src/browser/notifications.ts",
     "./browser/resource-clipboard": "./src/browser/resource-clipboard.ts",
+    "./browser/commands": "./src/browser/commands.ts",
+    "./browser/search": "./src/browser/search.ts",
+    "./browser/testing": "./src/browser/testing.ts",
     "./browser/resource-picker": "./src/browser/resource-picker.tsx",
     "./capabilities": "./src/capabilities/client.ts",
     "./capabilities/server": "./src/capabilities/server.ts",
+    "./capabilities/store": "./src/capabilities/executions.ts",
     "./capabilities/testing": "./src/capabilities/testing.ts",
     "./cli": "./src/cli/index.ts",
     "./cli/access": "./src/cli/access.ts",
@@ -57,6 +64,7 @@
     "./access/ui": "./src/access/ui.ts",
     "./ssr": "./src/ssr/index.ts",
     "./ssr/islands": "./src/ssr/islands/index.ts",
+    "./ssr/WorkspaceNavigation.island": "./src/ssr/WorkspaceNavigation.island.tsx",
     "./ssr/*": "./src/ssr/*",
     "./config": "./src/config/index.ts",
     "./config/*": "./src/config/*",
@@ -75,23 +83,26 @@
     "./styles/global.css": "./src/styles/global.css"
   },
   "scripts": {
-    "test": "bun test",
+    "test": "bun test --isolate --path-ignore-patterns '**/*.behavior.test.tsx' --path-ignore-patterns '**/*.dom.test.tsx' && bun run test:dom",
+    "test:dom": "bun test --isolate --conditions=browser --preload ../ui/test/solid-dom-preload.ts behavior.test.tsx dom.test.tsx",
     "typecheck": "tsc -p tsconfig.json --noEmit --pretty false 2>&1 | grep -v node_modules | (! grep -q 'error TS')"
   },
   "dependencies": {
     "@firecrawl/anydoc": "0.1.9",
-    "@k2b/nessi": "0.11.0",
-    "@k2b/ssr": "0.12.0",
-    "@k2b/stdlib": "0.22.0",
-    "@k2b/sync": "6.4.0",
-    "@k2b/ui": "0.2.0",
-    "@modelcontextprotocol/sdk": "1.30.0",
-    "@nats-io/transport-node": "3.4.0",
+    "@napi-rs/canvas": "1.0.8",
+    "pdfjs-dist": "6.3.289",
+    "@hono/standard-validator": "0.2.2",
     "@simplewebauthn/server": "13.3.2",
     "@tabler/icons": "3.46.0",
     "@tailwindcss/typography": "0.5.20",
+    "@k2b/nessi": "0.12.0",
+    "@k2b/ssr": "0.14.0",
+    "@k2b/ui": "0.3.0",
+    "@k2b/stdlib": "0.25.0",
+    "@k2b/sync": "6.4.0",
+    "@nats-io/transport-node": "3.4.0",
+    "@modelcontextprotocol/sdk": "1.30.0",
     "bun-plugin-tailwind": "0.1.2",
-    "hash-wasm": "4.12.0",
     "hono-openapi": "1.3.1",
     "jose": "6.2.5",
     "katex": "0.16.47",
@@ -105,20 +116,22 @@
     "seroval": "1.6.0",
     "tailwindcss": "4.3.3",
     "web-push": "3.6.7",
-    "yaml": "2.9.0"
+    "web-vitals": "6.2.1",
+    "yaml": "2.9.0",
+    "hash-wasm": "4.12.0",
+    "@types/nodemailer": "7.0.12",
+    "@types/sanitize-html": "2.16.1",
+    "@types/web-push": "3.6.4"
   },
   "devDependencies": {
     "@babel/core": "7.29.7",
     "@babel/preset-typescript": "7.29.7",
-    "@types/bun": "1.3.14",
-    "@types/nodemailer": "7.0.12",
-    "@types/sanitize-html": "2.16.1",
-    "@types/web-push": "3.6.4",
+    "@types/bun": "1.4.2",
     "babel-preset-solid": "1.9.12",
     "hono": "4.12.32",
     "solid-js": "1.9.14",
     "typescript": "5.9.3",
-    "zod": "4.4.3"
+    "zod": "4.6.2"
   },
   "peerDependencies": {
     "hono": "^4.12.25",

package/scripts/browser-performance.ts

@@ -0,0 +1,14 @@
+import { resolve } from "node:path";
+import { WEB_VITALS_ASSET_NAME } from "../src/_internal/web-vitals-asset";
+
+export async function buildBrowserPerformance(publicDir: string, appId: string): Promise<void> {
+  if (appId !== "core") return;
+  const result = await Bun.build({
+    entrypoints: [resolve(import.meta.dir, "../src/browser/web-vitals.ts")],
+    outdir: publicDir,
+    naming: WEB_VITALS_ASSET_NAME,
+    target: "browser",
+    minify: true,
+  });
+  if (!result.success) throw new AggregateError(result.logs, "Browser performance build failed");
+}

package/scripts/build-pdf-renderer.ts

@@ -0,0 +1,39 @@
+import { cp, mkdir } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+
+/** Package the decoder and native assets only for bundles importing PDF vision. */
+export async function buildPdfRenderer(dist: string) {
+  const framework = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+  const out = resolve(dist, "pdf-render");
+  await mkdir(out, { recursive: true });
+  const worker = await Bun.build({
+    entrypoints: [resolve(framework, "src/ai/pdf-render-worker.ts")],
+    target: "bun",
+    outdir: out,
+    naming: "worker.js",
+    external: ["pdfjs-dist", "@napi-rs/canvas"],
+  });
+  if (!worker.success) throw new Error(`PDF decoder build failed: ${worker.logs.join("\n")}`);
+  for (const name of ["pdfjs-dist", "@napi-rs/canvas"]) {
+    const source = dirname(Bun.resolveSync(`${name}/package.json`, framework));
+    await cp(source, resolve(out, "node_modules", name), { recursive: true, dereference: true });
+    if (name !== "@napi-rs/canvas") continue;
+    const manifest = z
+      .object({ optionalDependencies: z.record(z.string(), z.string()) })
+      .parse(await Bun.file(resolve(source, "package.json")).json());
+    let nativePackages = 0;
+    for (const dependency of Object.keys(manifest.optionalDependencies)) {
+      let location: string;
+      try {
+        location = dirname(Bun.resolveSync(`${dependency}/package.json`, source));
+      } catch {
+        continue;
+      } // Only the installed target-platform binary is needed.
+      await cp(location, resolve(out, "node_modules", dependency), { recursive: true, dereference: true });
+      nativePackages++;
+    }
+    if (!nativePackages) throw new Error("PDF decoder needs an installed native canvas binary for the build platform.");
+  }
+}

package/scripts/build.ts

@@ -4,11 +4,11 @@
  * Two consumer shapes:
  *
  *   Monorepo (this repo):
- *     APP_ID=<id> bun run packages/cloud/scripts/build.ts
+ *     NODE_ENV=production APP_ID=<id> bun run packages/cloud/scripts/build.ts
  *     # appDir defaults to packages/<APP_ID>, run from workspace root.
  *
  *   Standalone (npm consumer, see cloud-template):
- *     APP_ID=<id> APP_DIR=. bun run node_modules/@k2b/cloud/scripts/build.ts
+ *     NODE_ENV=production APP_ID=<id> APP_DIR=. bun run node_modules/@k2b/cloud/scripts/build.ts
  *     # appDir = APP_DIR (resolved against cwd) and must be the directory
  *     # that CONTAINS src/, since entrypoints resolve to <appDir>/src/*.
  *
@@ -22,20 +22,21 @@
  * it ships a `scripts/build-extras.ts` that this script runs at the end.
  */
 import { existsSync } from "node:fs";
-import { cp, mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname, extname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 import { brotliCompress, gzip, constants as zlibConstants } from "node:zlib";
-import { CryptoHasher, Glob } from "bun";
+import { Glob } from "bun";
 import tailwind from "bun-plugin-tailwind";
 import { writeAppFavicon } from "./app-favicon";
+import { buildBrowserPerformance } from "./browser-performance";
+import { buildPdfRenderer } from "./build-pdf-renderer";
 
 const appId = process.env.APP_ID;
 if (!appId) throw new Error("APP_ID env var required");
 
-// `root` = wherever the user is building from. SSR plugin's rootDir is
-// process.cwd() (set in defineApp), so we use the same here for hash parity.
+// Build output is relative to the consuming project, including npm consumers.
 const root = process.cwd();
 
 // Framework dir — works whether this script is in packages/cloud/scripts/
@@ -59,6 +60,8 @@ const syncVersion = syncPackage.version;
 // convention. Resolved against cwd if relative.
 const appDir = process.env.APP_DIR ? resolve(root, process.env.APP_DIR) : resolve(root, "packages", appId);
 if (!existsSync(appDir)) throw new Error(`Unknown app dir: ${appDir} (set APP_DIR or check APP_ID)`);
+// Share the resolved source directory with defineApp before importing config.
+process.env.APP_DIR = appDir;
 
 const dist = resolve(root, "dist");
 const distPublic = resolve(dist, "public");
@@ -68,14 +71,6 @@ const compressGzip = promisify(gzip);
 await rm(dist, { recursive: true, force: true });
 await mkdir(distPublic, { recursive: true });
 
-// Mirrors @k2b/ssr's island-id (md5 of POSIX path relative to the
-// SSR plugin's rootDir, truncated to 12 chars). Both this script and the
-// plugin use process.cwd() as the rootDir, so hashes match.
-const islandId = (file: string): string => {
-  const rel = file.slice(root.length + 1).replace(/\\/g, "/");
-  return new CryptoHasher("md5").update(rel).digest("hex").slice(0, 12);
-};
-
 const compressibleExtensions = new Set([".css", ".html", ".js", ".json", ".map", ".svg", ".txt", ".xml"]);
 
 async function precompressDistAssets(dir: string): Promise<void> {
@@ -124,11 +119,13 @@ try {
     naming: "server.js",
     target: "bun",
     minify: true,
+    metafile: true,
     define: {
       __CLOUD_RELEASE__: JSON.stringify(release),
       __CLOUD_SYNC_VERSION__: JSON.stringify(syncVersion),
+      __CLOUD_PDF_RENDER_WORKER__: JSON.stringify("./pdf-render/worker.js"),
     },
-    plugins: [plugin()],
+    plugins: [(app?.plugin ?? plugin)()],
   });
 } finally {
   await rm(serverEntry, { force: true });
@@ -137,26 +134,8 @@ if (!server.success) {
   for (const m of server.logs) console.error(m);
   throw new Error("Server bundle failed");
 }
-
-// 1b. The SSR plugin scans the project root and emits one chunk per island
-//     across every reachable package (including any island-shaped files in
-//     other workspace packages or in node_modules). Keep only this app's own
-//     islands plus the framework's; drop the rest. chunk-* files are shared
-//     splits and always kept.
-const ssrDir = resolve(dist, "_ssr");
-if (existsSync(ssrDir)) {
-  const allowedDirs = [frameworkDir, appDir];
-  const allowedIds = new Set<string>();
-  for (const dir of allowedDirs) {
-    for await (const file of new Glob("**/*.{island,client}.tsx").scan({ cwd: dir, absolute: true })) {
-      allowedIds.add(islandId(file));
-    }
-  }
-  for (const entry of await readdir(ssrDir)) {
-    if (entry.startsWith("chunk-") || !entry.endsWith(".js")) continue;
-    const id = entry.slice(0, -3);
-    if (!allowedIds.has(id)) await rm(resolve(ssrDir, entry));
-  }
+if (Object.keys(server.metafile?.inputs ?? {}).some(path => path.endsWith("/ai/pdf-render.ts"))) {
+  await buildPdfRenderer(dist);
 }
 
 // 2. Per-app Tailwind stylesheet.
@@ -199,6 +178,7 @@ if (existsSync(extras)) {
   await import(extras);
 }
 
+await buildBrowserPerformance(distPublic, appId);
 await precompressDistAssets(resolve(dist, "public"));
 await precompressDistAssets(resolve(dist, "_ssr"));
 

package/scripts/preload.ts

@@ -23,6 +23,7 @@ import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import tailwind from "bun-plugin-tailwind";
 import { writeAppFavicon } from "./app-favicon";
+import { buildBrowserPerformance } from "./browser-performance";
 
 const appId = process.env.APP_ID ?? "core";
 
@@ -38,9 +39,11 @@ const frameworkDir = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 // convention. Resolved against cwd if relative.
 const appDir = process.env.APP_DIR ? resolve(root, process.env.APP_DIR) : resolve(root, "packages", appId);
 if (!existsSync(appDir)) throw new Error(`Unknown app dir: ${appDir} (set APP_DIR or check APP_ID)`);
+// Share the resolved source directory with defineApp before importing config.
+process.env.APP_DIR = appDir;
 
 const { app, plugin } = await import(resolve(appDir, "src/config"));
-Bun.plugin(plugin());
+Bun.plugin((app?.plugin ?? plugin)());
 
 // ── Build CSS ───────────────────────────────────────────────────────────────
 const publicDir = resolve(root, "public");
@@ -125,15 +128,6 @@ if (appId === "core" && existsSync(globalCssEntry)) {
   await cp(resolve(frameworkDir, "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(root, "node_modules/katex/dist/katex.min.css"), resolve(publicDir, "katex.css"));
-  } catch {
-    console.warn("[preload] katex.css not found, skipping");
-  }
-}
-
 // Each app builds its own app.css
 const appPublicDir = resolve(publicDir, appId);
 await mkdir(appPublicDir, { recursive: true });
@@ -146,9 +140,12 @@ if (appId !== "core" && app) {
   });
 }
 
-await buildAppCss();
+if (existsSync(appCssPath)) {
+  await buildAppCss();
+  watchDevCss("app.css", [resolve(appCssPath, "..")], buildAppCss);
+}
+await buildBrowserPerformance(publicDir, appId);
 
-watchDevCss("app.css", [resolve(appCssPath, "..")], buildAppCss);
 if (appId === "core" && existsSync(globalCssEntry)) {
   watchDevCss("global.css", [globalCssEntry, resolve(frameworkDir, "src/styles")], buildGlobalCss);
 }

package/scripts/sync-recovery-smoke.ts

@@ -7,6 +7,7 @@
  * No provider or application-domain effects; successful recovery deletes only
  * the exact test streams after checking their broker identity metadata.
  */
+import { env } from "../src/config/env";
 import { createSync, type SyncResourceSummary, type Worker } from "@k2b/sync";
 import { connect, type NatsConnection } from "@nats-io/transport-node";
 
@@ -57,7 +58,7 @@ export const main = async (): Promise<void> => {
     .map((value) => value.trim())
     .filter(Boolean);
   const connection = await connect({ servers, name: `${APPLICATION}-${phase}`, ignoreClusterUpdates: true });
-  const sync = createSync({ connection, namespace, application: APPLICATION, defaults: { replicas: 3 } });
+  const sync = createSync({ connection, namespace, application: APPLICATION, defaults: { replicas: env.SYNC_REPLICAS } });
   const job = sync.job<{ preparedAt: string }>({
     id: JOB_ID,
     delivery: { ackWaitMs: 30_000, maxAttempts: 3, backoffMs: [1_000, 2_000] },

package/src/_internal/app-presentation.ts

@@ -11,12 +11,12 @@ const text = (value: string, label: string, max = MAX_SHORT_TEXT): string => {
   return normalized;
 };
 
-const labels = (values: Readonly<Record<string, string>> | undefined, allowed: Set<string>, label: string) => {
+const labels = (values: Readonly<Record<string, string>> | undefined, allowed: Set<string>, label: string, max = MAX_SHORT_TEXT) => {
   if (!values) return undefined;
   const normalized: Record<string, string> = {};
   for (const [key, value] of Object.entries(values)) {
     if (!allowed.has(key)) throw new Error(`${label} contains unknown key ${JSON.stringify(key)}`);
-    normalized[key] = text(value, `${label}.${key}`);
+    normalized[key] = text(value, `${label}.${key}`, max);
   }
   return normalized;
 };
@@ -34,6 +34,7 @@ export const compileAppPresentation = (app: AppMeta, catalog: AppPresentationCat
     groupIds.add(group.id);
   }
   const adminHrefs = new Set((app.adminNav ?? []).flatMap((group) => group.links.map((link) => link.href)));
+  const searchHrefs = new Set((app.searchLinks ?? []).map((link) => link.href));
   const legalHrefs = new Set((app.legalLinks ?? []).map((link) => link.href));
   const translations: Record<string, AppPresentationTranslation> = {};
 
@@ -49,6 +50,17 @@ export const compileAppPresentation = (app: AppMeta, catalog: AppPresentationCat
         : {}),
       ...(translation.adminGroups ? { adminGroups: labels(translation.adminGroups, groupIds, `${canonical}.adminGroups`) } : {}),
       ...(translation.adminLinks ? { adminLinks: labels(translation.adminLinks, adminHrefs, `${canonical}.adminLinks`) } : {}),
+      ...(translation.searchLinks ? { searchLinks: labels(translation.searchLinks, searchHrefs, `${canonical}.searchLinks`) } : {}),
+      ...(translation.searchLinkDescriptions
+        ? {
+            searchLinkDescriptions: labels(
+              translation.searchLinkDescriptions,
+              searchHrefs,
+              `${canonical}.searchLinkDescriptions`,
+              MAX_DESCRIPTION,
+            ),
+          }
+        : {}),
       ...(translation.legalLinks ? { legalLinks: labels(translation.legalLinks, legalHrefs, `${canonical}.legalLinks`) } : {}),
     };
   }