@k2b/cloud 0.6.0-rc.0

package/scripts/preload.ts

@@ -0,0 +1,164 @@
+/**
+ * Preload script for dev mode.
+ * Registers the SSR plugin (Solid.js JSX transform + island bundling)
+ * and builds CSS before any app code is imported.
+ *
+ * Mirrors the two consumer shapes of scripts/build.ts:
+ *
+ *   Monorepo (this repo):
+ *     APP_ID=<id> bun run --preload=packages/cloud/scripts/preload.ts ...
+ *     # appDir defaults to packages/<APP_ID>, run from workspace root.
+ *
+ *   Standalone (npm consumer, see cloud-template):
+ *     APP_ID=<id> APP_DIR=. bun run --preload=node_modules/@k2b/cloud/scripts/preload.ts ...
+ *     # appDir = APP_DIR (resolved against cwd), i.e. the directory holding src/.
+ *
+ * Uses bun-plugin-tailwind with root=cwd for stable path resolution. Each app
+ * stylesheet owns an explicit, app-local @source contract so the development
+ * build cannot leak classes from sibling apps.
+ */
+import { existsSync, watch } from "node:fs";
+import { cp, mkdir } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import tailwind from "bun-plugin-tailwind";
+import { writeAppFavicon } from "./app-favicon";
+
+const appId = process.env.APP_ID ?? "core";
+
+// `root` = wherever the process was started. In the monorepo this is the
+// workspace root, which is what the paths below used to be resolved against.
+const root = process.cwd();
+
+// Framework dir — works whether this script sits in packages/cloud/scripts/
+// (monorepo) or node_modules/@k2b/cloud/scripts/ (npm install).
+const frameworkDir = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+// App dir — APP_DIR override for standalone consumers, defaults to monorepo
+// 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)`);
+
+const { app, plugin } = await import(resolve(appDir, "src/config"));
+Bun.plugin(plugin());
+
+// ── Build CSS ───────────────────────────────────────────────────────────────
+const publicDir = resolve(root, "public");
+await mkdir(publicDir, { recursive: true });
+
+const globalCssEntry = resolve(root, "styles.css");
+
+const buildGlobalCss = async () => {
+  // Use the same global entrypoint as the production extras build.
+  await Bun.build({
+    entrypoints: [globalCssEntry],
+    outdir: publicDir,
+    naming: "global.css",
+    plugins: [tailwind],
+  });
+};
+
+const appCssPath = resolve(appDir, "src/styles/app.css");
+
+const buildAppCss = async () => {
+  // `naming: "app.css"` is essential — without it, Bun.build with `root` set
+  // 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: resolve(publicDir, appId),
+    naming: "app.css",
+    root,
+    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).
+// A standalone app consumes both from the prebuilt core container, so the
+// workspace entrypoint is absent there and this block simply does not run.
+if (appId === "core" && existsSync(globalCssEntry)) {
+  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(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 });
+
+if (appId !== "core" && app) {
+  await writeAppFavicon({
+    publicDir,
+    appId,
+    icon: app.meta.icon,
+  });
+}
+
+await buildAppCss();
+
+watchDevCss("app.css", [resolve(appCssPath, "..")], buildAppCss);
+if (appId === "core" && existsSync(globalCssEntry)) {
+  watchDevCss("global.css", [globalCssEntry, resolve(frameworkDir, "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(appDir, "scripts/dev-extras.ts");
+if (existsSync(devExtras)) {
+  process.env.WORKSPACE_ROOT = root;
+  process.env.PUBLIC_DIR = publicDir;
+  await import(devExtras);
+}

package/scripts/sync-recovery-smoke.ts

@@ -0,0 +1,200 @@
+/**
+ * Isolated two-process recovery acceptance for the local NATS cluster.
+ *
+ * SYNC_RECOVERY_NAMESPACE=cloud-recovery-smoke-<unique> bun packages/cloud/scripts/sync-recovery-smoke.ts prepare
+ * Stop the application fleet across the printed nextTick boundary, keeping NATS up.
+ * Restart the fleet, then run the same command with `recover`.
+ * No provider or application-domain effects; successful recovery deletes only
+ * the exact test streams after checking their broker identity metadata.
+ */
+import { createSync, type SyncResourceSummary, type Worker } from "@k2b/sync";
+import { connect, type NatsConnection } from "@nats-io/transport-node";
+
+const APPLICATION = "cloud-recovery-smoke";
+const JOB_ID = "restart-job";
+const SCHEDULER_ID = "restart-scheduler";
+const SCHEDULE_ID = "minute";
+const WAIT_MS = 20_000;
+const object = (value: unknown): Record<string, unknown> => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Expected a broker object response");
+  return Object.fromEntries(Object.entries(value));
+};
+function check(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+
+const removeTestStreams = async (connection: NatsConnection, namespace: string, resources: SyncResourceSummary[]) => {
+  let deleted = 0;
+  for (const resource of resources) {
+    check(resource.namespace === namespace && resource.owner === APPLICATION, "Refusing to remove a foreign resource");
+    check(resource.id === JOB_ID || resource.id === SCHEDULER_ID, "Refusing to remove an unexpected resource");
+    for (const name of resource.natsNames) {
+      check(/^[A-Za-z0-9_-]+$/.test(name), "Invalid broker stream name");
+      const info = object((await connection.request(`$JS.API.STREAM.INFO.${name}`, new Uint8Array())).json<unknown>());
+      const metadata = object(object(info.config).metadata);
+      check(
+        metadata["sync.managed"] === "true" &&
+          metadata["sync.namespace"] === namespace &&
+          metadata["sync.owner"] === APPLICATION &&
+          metadata["sync.id"] === resource.id,
+        "Broker identity does not match the isolated recovery resource",
+      );
+      const removed = object((await connection.request(`$JS.API.STREAM.DELETE.${name}`, new Uint8Array())).json<unknown>());
+      check(removed.success === true, "Broker refused recovery stream cleanup");
+      deleted++;
+    }
+  }
+  return deleted;
+};
+
+export const main = async (): Promise<void> => {
+  const phase = Bun.argv[2];
+  check(phase === "prepare" || phase === "recover", "Pass prepare or recover");
+  const namespace = process.env.SYNC_RECOVERY_NAMESPACE?.trim() ?? "";
+  check(/^cloud-recovery-smoke-[A-Za-z0-9_-]{6,60}$/.test(namespace), "Set a unique SYNC_RECOVERY_NAMESPACE=cloud-recovery-smoke-<suffix>");
+  const servers = (process.env.NATS_SERVERS ?? "nats://127.0.0.1:4222")
+    .split(",")
+    .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 job = sync.job<{ preparedAt: string }>({
+    id: JOB_ID,
+    delivery: { ackWaitMs: 30_000, maxAttempts: 3, backoffMs: [1_000, 2_000] },
+  });
+  const scheduler = sync.scheduler({ id: SCHEDULER_ID, delivery: { maxAttempts: 3, backoffMs: [1_000, 2_000] } });
+  const workers: Worker[] = [];
+  let drained = false;
+  try {
+    await sync.ready();
+    if (phase === "prepare") {
+      check((await scheduler.get({ id: SCHEDULE_ID })) === null, "Namespace already prepared; use a new unique namespace");
+      const preparedAt = new Date().toISOString();
+      await scheduler.create({
+        id: SCHEDULE_ID,
+        cron: "* * * * *",
+        timezone: "UTC",
+        misfire: "latest",
+        meta: { preparedAt },
+        process: async () => {
+          throw new Error("Prepare phase must not start schedule workers");
+        },
+      });
+      const receipt = await job.submit({ key: "pending-before-stop", input: { preparedAt }, coalesce: true });
+      const schedule = await scheduler.get({ id: SCHEDULE_ID });
+      check(schedule?.nextRunAt, "Broker did not persist the recovery schedule");
+      console.log(
+        JSON.stringify({
+          phase,
+          namespace,
+          preparedAt,
+          nextTick: schedule.nextRunAt.toISOString(),
+          jobId: receipt.jobId,
+          workersStarted: 0,
+        }),
+      );
+      return;
+    }
+
+    const recoveredAt = Date.now();
+    const existing = await scheduler.get({ id: SCHEDULE_ID });
+    check(existing, "Prepared schedule missing; recovery cannot prove persistence");
+    const preparedAt = existing.meta?.preparedAt;
+    check(typeof preparedAt === "string" && Number.isFinite(Date.parse(preparedAt)), "Prepared schedule metadata missing");
+    check(existing.runNumber === 0, "Prepared schedule was already processed");
+    const firstTick = Math.floor(Date.parse(preparedAt) / 60_000) * 60_000 + 60_000;
+    check(recoveredAt > firstTick, "No missed minute boundary yet; leave NATS running until after nextTick");
+    const jobDone = Promise.withResolvers<void>();
+    const tickDone = Promise.withResolvers<void>();
+    let jobs = 0;
+    let ticks = 0;
+    let recoveredSlot: string | undefined;
+    const registration = await scheduler.create({
+      id: SCHEDULE_ID,
+      cron: "* * * * *",
+      timezone: "UTC",
+      misfire: "latest",
+      meta: { preparedAt },
+      process: async (context) => {
+        check(context.trigger === "schedule", "Expected a broker cron tick, not a manual run");
+        check(
+          context.slot.getTime() >= firstTick && context.slot.getTime() < recoveredAt,
+          "Cron tick was not retained from the offline interval",
+        );
+        recoveredSlot = context.slot.toISOString();
+        ticks++;
+        tickDone.resolve();
+      },
+    });
+    check(!registration.created && !registration.updated, "Re-registration unexpectedly changed the persisted schedule");
+    workers.push(
+      await job.process({ concurrency: 1 }, async (context) => {
+        check(context.input.preparedAt === preparedAt && context.key === "pending-before-stop", "Unexpected recovery job payload");
+        jobs++;
+        jobDone.resolve();
+      }),
+    );
+    workers.push(await scheduler.process({ concurrency: 1 }));
+    let timeout: ReturnType<typeof setTimeout> | undefined;
+    try {
+      await Promise.race([
+        Promise.all([jobDone.promise, tickDone.promise]),
+        new Promise<never>((_, reject) => {
+          timeout = setTimeout(() => reject(new Error("Retained job or cron tick was not recovered within 20 seconds")), WAIT_MS);
+        }),
+      ]);
+    } finally {
+      if (timeout) clearTimeout(timeout);
+    }
+    for (const worker of workers) worker.stop();
+    await Promise.all(workers.map((worker) => worker.drain()));
+    check(jobs === 1 && ticks === 1, "Unexpected duplicate work during isolated recovery");
+    const finalSchedule = await scheduler.get({ id: SCHEDULE_ID });
+    check(finalSchedule?.lastCompletedAt, "Recovered cron tick did not settle successfully");
+    const resources = await sync.resources();
+    check(
+      resources.every((resource) => resource.state === "ready"),
+      "Recovery resources are not ready",
+    );
+    check(
+      resources.every((resource) => !resource.detail?.deadLetters),
+      "Recovery created dead letters",
+    );
+    const recoveredJob = resources.find((resource) => resource.kind === "job" && resource.id === JOB_ID);
+    check(recoveredJob?.detail?.messages === 0, "Recovery job remains in the broker stream after drain");
+    const consumers = object(recoveredJob.detail.consumers);
+    check(Object.keys(consumers).length > 0, "Recovery job consumer diagnostics are missing");
+    for (const state of Object.values(consumers)) {
+      const consumer = object(state);
+      check(consumer.pending === 0 && consumer.ackPending === 0, "Recovery job has pending or unacknowledged broker deliveries");
+    }
+    await scheduler.delete({ id: SCHEDULE_ID });
+    await sync.drain();
+    drained = true;
+    const deletedStreams = await removeTestStreams(connection, namespace, resources);
+    console.log(
+      JSON.stringify({
+        phase,
+        namespace,
+        preparedAt,
+        recoveredAt: new Date(recoveredAt).toISOString(),
+        recoveredSlot,
+        jobs,
+        ticks,
+        pendingJobMessages: recoveredJob.detail.messages,
+        unacknowledgedJobMessages: 0,
+        deletedStreams,
+        outcome: "passed",
+      }),
+    );
+  } finally {
+    for (const worker of workers) worker.stop();
+    try {
+      if (!drained) await sync.drain();
+    } finally {
+      await connection.drain();
+    }
+  }
+};
+
+if (import.meta.main) await main();

package/src/_internal/app-favicon.ts

@@ -0,0 +1,2 @@
+export const appFaviconHref = (appId: string, version: number): string =>
+  appId === "core" ? "/branding/favicon" : `/public/${appId}/favicon.svg?v=${version}`;

package/src/_internal/app-presentation.ts

@@ -0,0 +1,61 @@
+import type { AppMeta, AppPresentationCatalog, AppPresentationTranslation } from "../contracts/app";
+import { canonicalLocale } from "../shared/locale";
+
+export const APP_PRESENTATION_MAX_BYTES = 64 * 1024;
+const MAX_SHORT_TEXT = 200;
+const MAX_DESCRIPTION = 2_000;
+
+const text = (value: string, label: string, max = MAX_SHORT_TEXT): string => {
+  const normalized = value.trim();
+  if (!normalized || normalized.length > max) throw new Error(`${label} must contain 1 to ${max} characters`);
+  return normalized;
+};
+
+const labels = (values: Readonly<Record<string, string>> | undefined, allowed: Set<string>, label: string) => {
+  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}`);
+  }
+  return normalized;
+};
+
+/** Validate and canonicalize one static app-presentation catalog before it enters the registry. */
+export const compileAppPresentation = (app: AppMeta, catalog: AppPresentationCatalog | undefined): AppPresentationCatalog | undefined => {
+  if (!catalog) return undefined;
+  const baseLocale = canonicalLocale(catalog.baseLocale);
+  if (!baseLocale) throw new Error("App presentation baseLocale must be a valid BCP 47 locale");
+
+  const groupIds = new Set<string>();
+  for (const group of app.adminNav ?? []) {
+    if (!group.id) continue;
+    if (groupIds.has(group.id)) throw new Error(`App presentation admin group id ${JSON.stringify(group.id)} is duplicated`);
+    groupIds.add(group.id);
+  }
+  const adminHrefs = new Set((app.adminNav ?? []).flatMap((group) => group.links.map((link) => link.href)));
+  const legalHrefs = new Set((app.legalLinks ?? []).map((link) => link.href));
+  const translations: Record<string, AppPresentationTranslation> = {};
+
+  for (const [locale, translation] of Object.entries(catalog.translations)) {
+    const canonical = canonicalLocale(locale);
+    if (!canonical) throw new Error(`App presentation locale ${JSON.stringify(locale)} is not a valid BCP 47 locale`);
+    if (canonical === baseLocale) throw new Error(`App presentation translations must not repeat base locale ${baseLocale}`);
+    if (translations[canonical]) throw new Error(`App presentation locale ${canonical} is duplicated after canonicalization`);
+    translations[canonical] = {
+      ...(translation.name !== undefined ? { name: text(translation.name, `${canonical}.name`) } : {}),
+      ...(translation.description !== undefined
+        ? { description: text(translation.description, `${canonical}.description`, MAX_DESCRIPTION) }
+        : {}),
+      ...(translation.adminGroups ? { adminGroups: labels(translation.adminGroups, groupIds, `${canonical}.adminGroups`) } : {}),
+      ...(translation.adminLinks ? { adminLinks: labels(translation.adminLinks, adminHrefs, `${canonical}.adminLinks`) } : {}),
+      ...(translation.legalLinks ? { legalLinks: labels(translation.legalLinks, legalHrefs, `${canonical}.legalLinks`) } : {}),
+    };
+  }
+
+  const compiled = { baseLocale, translations } satisfies AppPresentationCatalog;
+  if (new TextEncoder().encode(JSON.stringify(compiled)).byteLength > APP_PRESENTATION_MAX_BYTES) {
+    throw new Error(`App presentation catalog exceeds ${APP_PRESENTATION_MAX_BYTES} bytes`);
+  }
+  return compiled;
+};

package/src/_internal/app-workspace-state.ts

@@ -0,0 +1,24 @@
+import { type AppWorkspaceLayoutState, parseAppWorkspaceLayoutState } from "@k2b/ui";
+
+const safeAppId = (appId: string): string => appId.replace(/[^A-Za-z0-9_-]/g, "_");
+
+export const appWorkspaceCookieName = (appId: string): string => `cloud_workspace_${safeAppId(appId)}`;
+
+export const readAppWorkspaceLayoutCookie = (
+  cookieHeader: string | null | undefined,
+  appId: string | null | undefined,
+): AppWorkspaceLayoutState | null => {
+  if (!cookieHeader || !appId) return null;
+  const name = appWorkspaceCookieName(appId);
+  const encoded = cookieHeader
+    .split(";")
+    .map((part) => part.trim())
+    .find((part) => part.startsWith(`${name}=`))
+    ?.slice(name.length + 1);
+  return parseAppWorkspaceLayoutState(encoded);
+};
+
+export const resolveAppWorkspaceLayoutForSidebar = (
+  state: AppWorkspaceLayoutState | null,
+  collapsible: boolean | undefined,
+): AppWorkspaceLayoutState | null => (collapsible === false && state?.sidebarCollapsed ? { ...state, sidebarCollapsed: false } : state);

package/src/_internal/bounded-json.ts

@@ -0,0 +1,47 @@
+export type BoundedJsonResult = { ok: true; data: unknown } | { ok: false; reason: "too_large" | "invalid_json" };
+
+/** Reads JSON without allowing a missing or forged Content-Length to bypass the byte cap. */
+export const readBoundedJson = async (message: Request | Response, maxBytes: number): Promise<BoundedJsonResult> => {
+  const declared = message.headers.get("content-length");
+  if (declared !== null) {
+    const bytes = Number(declared);
+    if (Number.isFinite(bytes) && bytes > maxBytes) {
+      await message.body?.cancel().catch(() => undefined);
+      return { ok: false, reason: "too_large" };
+    }
+  }
+
+  const reader = message.body?.getReader();
+  if (!reader) return { ok: false, reason: "invalid_json" };
+
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  try {
+    while (true) {
+      const next = await reader.read();
+      if (next.done) break;
+      total += next.value.byteLength;
+      if (total > maxBytes) {
+        await reader.cancel().catch(() => undefined);
+        return { ok: false, reason: "too_large" };
+      }
+      chunks.push(next.value);
+    }
+  } catch {
+    await reader.cancel().catch(() => undefined);
+    return { ok: false, reason: "invalid_json" };
+  }
+
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+
+  try {
+    return { ok: true, data: JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)) };
+  } catch {
+    return { ok: false, reason: "invalid_json" };
+  }
+};

package/src/_internal/build-metadata.ts

@@ -0,0 +1,9 @@
+import type { AppRuntimeMetadata } from "../contracts/registry";
+
+declare const __CLOUD_RELEASE__: string;
+declare const __CLOUD_SYNC_VERSION__: string;
+
+export const appRuntimeMetadata: AppRuntimeMetadata = {
+  release: typeof __CLOUD_RELEASE__ === "string" ? __CLOUD_RELEASE__ : "development",
+  syncVersion: typeof __CLOUD_SYNC_VERSION__ === "string" ? __CLOUD_SYNC_VERSION__ : "unknown",
+};