@valentinkolb/cloud 0.1.2 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valentinkolb/cloud",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Modular Hono+SolidJS framework for building per-app docker services behind a dynamic gateway. Powers cloud.stuve-ulm.de.",
   "license": "MIT",
   "repository": {

package/scripts/build.ts

@@ -1,13 +1,21 @@
 /**
- * Production build for a single app.
+ * Production build for a single cloud app.
  *
- *   APP_ID=<id> bun run packages/cloud/scripts/build.ts
+ * Two consumer shapes:
  *
- * Output goes to /<workspace-root>/dist:
+ *   Monorepo (this repo):
+ *     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=src bun run node_modules/@valentinkolb/cloud/scripts/build.ts
+ *     # appDir = APP_DIR (resolved against cwd).
+ *
+ * Output goes to <cwd>/dist:
  *   server.js            bundled Bun entry
  *   _ssr/<island>.js     hydration bundles (auto-emitted by the SSR plugin)
  *   public/<id>/app.css  Tailwind, if the app has src/styles/app.css
- *   public/<id>/...      anything from packages/<id>/public/
+ *   public/<id>/...      anything from <appDir>/public/
  *
  * If the app needs additional artefacts (core's global.css, logo, katex),
  * it ships a `scripts/build-extras.ts` that this script runs at the end.
@@ -19,21 +27,23 @@ import { fileURLToPath } from "node:url";
 import tailwind from "bun-plugin-tailwind";
 import { Glob, CryptoHasher } from "bun";
 
-// Mirrors @valentinkolb/ssr's island-id (md5 of POSIX path relative to the
-// SSR plugin's rootDir, truncated to 12 chars). define-app sets rootDir to
-// the `packages` directory.
-const ssrRootDir = "packages";
-const islandId = (file: string): string => {
-  const rel = file.slice(root.length + 1 + ssrRootDir.length + 1).replace(/\\/g, "/");
-  return new CryptoHasher("md5").update(rel).digest("hex").slice(0, 12);
-};
-
 const appId = process.env.APP_ID;
 if (!appId) throw new Error("APP_ID env var required");
 
-const root = resolve(dirname(fileURLToPath(import.meta.url)), "../../..");
-const appDir = resolve(root, "packages", appId);
-if (!existsSync(appDir)) throw new Error(`Unknown app: ${appId} (no packages/${appId})`);
+// `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.
+const root = process.cwd();
+
+// Framework dir — works whether this script is in packages/cloud/scripts/
+// (monorepo) or node_modules/@valentinkolb/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 dist = resolve(root, "dist");
 const distPublic = resolve(dist, "public");
@@ -41,8 +51,20 @@ const distPublic = resolve(dist, "public");
 await rm(dist, { recursive: true, force: true });
 await mkdir(distPublic, { recursive: true });
 
+// Mirrors @valentinkolb/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);
+};
+
 // Register the app's SSR plugin (Solid JSX transform + island bundler).
-const { plugin } = await import(`../../${appId}/src/config`);
+// In the monorepo this resolves via `packages/<id>/src/config`; in standalone
+// it resolves via the appDir path (because the script's relative imports
+// only work for monorepo, we use absolute file:// for standalone).
+const configPath = resolve(appDir, "src/config");
+const { plugin } = await import(configPath);
 
 // 1. Server entry — also emits dist/_ssr/<island>.js via the SSR plugin.
 const server = await Bun.build({
@@ -58,13 +80,14 @@ if (!server.success) {
   throw new Error("Server bundle failed");
 }
 
-// 1b. The SSR plugin scans the workspace root and emits one chunk per
-//     island/client file across every package. Drop the ones from other apps
-//     so this image only carries its own + the framework's. Chunk files
-//     (chunk-<hash>.js) are shared splits and always kept.
+// 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 = [resolve(root, "packages/cloud"), appDir];
+  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 })) {

package/src/_internal/define-app.ts

@@ -9,8 +9,6 @@ import { createSSRHandler, routes } from "@valentinkolb/ssr/hono";
 import { Hono } from "hono";
 import { serveStatic } from "hono/bun";
 import type { SsrConfig } from "@valentinkolb/ssr";
-import { resolve, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
 import type {
   AppMeta,
   AppLifecycle,
@@ -111,13 +109,26 @@ export type AppOptions<S extends AppSettingsMap = {}> = {
    * prefix-trie from these strings.
    */
   routes: readonly string[];
+  /**
+   * Project root used by the SSR plugin to discover island/client files.
+   * Defaults to `process.cwd()`. Override only if you run the entrypoint
+   * from a directory other than the project root.
+   */
+  appRoot?: string;
 };
 
 export type StartOptions = {
-  routes: {
-    api?: Hono<any>;
-    pages?: Hono<any>;
-  };
+  /**
+   * Single Hono instance mounted at `/` of the app's container. The app owns
+   * its full URL space — routes are written with their absolute paths
+   * (`/api/<id>`, `/app/<id>`, `/admin/<id>`, …), matching what the app
+   * declared in `defineApp({ routes: [...] })`.
+   *
+   * Framework-owned mounts (`/_ssr/*`, `/public/*`, `/api/_internal/search`)
+   * register before this router so they take precedence — apps can ignore
+   * those paths.
+   */
+  router: Hono<any>;
   lifecycle?: AppLifecycle;
   capabilities?: AppCapabilities;
   port?: number;
@@ -193,7 +204,7 @@ export const defineApp = <const S extends AppSettingsMap = {}>(opts: AppOptions<
   const { config, plugin, html } = createSsrConfig<PageOptions>({
     dev: process.env.NODE_ENV !== "production",
     verbose: true,
-    rootDir: resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", ".."),
+    rootDir: opts.appRoot ?? process.cwd(),
     basePath: opts.basePath,
     template: ({ body, scripts, title, description, theme }) => {
       const themeFixed = theme !== undefined;
@@ -332,13 +343,14 @@ export const defineApp = <const S extends AppSettingsMap = {}>(opts: AppOptions<
         onFound: (_path, c) => {
           c.header("Cache-Control", "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
+      // router (which might render an HTML page for the missing path).
+      .all("/public/*", (c) => c.notFound());
 
-    // Mount app routes
-    if (startOpts.routes.api) server.route("/api", startOpts.routes.api);
-    if (startOpts.routes.pages) server.route("/", startOpts.routes.pages);
-
-    // Internal search endpoint
+    // Framework-internal endpoints register BEFORE the app router so they
+    // take precedence over any catch-all the app might mount.
     if (startOpts.capabilities?.search) {
       const searchRun = startOpts.capabilities.search.run;
       server.post("/api/_internal/search", auth.requireRole("authenticated"), async (c) => {
@@ -349,6 +361,8 @@ export const defineApp = <const S extends AppSettingsMap = {}>(opts: AppOptions<
       });
     }
 
+    server.route("/", startOpts.router);
+
     // Lifecycle
     const cloudCtx: CloudContext = {
       logger,