@junejs/server 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 June.build
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,17 @@
+# @junejs/server
+
+June's host layer: the dev server, the render pipeline, the build (Workers
+bundle), and the host adapters (Bun / Node — detected at runtime). Depends
+inward on the pure `@junejs/core` contract layer; apps usually consume this
+through `@junejs/cli` rather than directly. **Preview (0.0.x): APIs will
+change.**
+
+```ts
+import { createApp, loadJuneConfig } from "@junejs/server";
+
+const app = createApp({ appDir, config: await loadJuneConfig(root) });
+// a June app is one Web-standard fetch handler
+export default { fetch: (req: Request) => app.fetch(req) };
+```
+
+Site & docs: [june.build](https://june.build).

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@junejs/server",
+  "version": "0.0.2",
+  "description": "June host adapters + dev server. Host-coupled; depends on the pure @junejs/core contract layer.",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://june.build",
+  "exports": {
+    ".": "./src/index.ts",
+    "./host": "./src/host.ts",
+    "./db": "./src/db.ts",
+    "./kv": "./src/kv.ts",
+    "./blob": "./src/blob.ts",
+    "./config": "./src/config-loader.ts",
+    "./content": "./src/content.ts",
+    "./router": "./src/router.ts",
+    "./instrumentation": "./src/instrumentation.ts",
+    "./pipeline": "./src/pipeline.ts",
+    "./worker": "./src/worker.ts",
+    "./build": "./src/build.ts",
+    "./deploy": "./src/deploy.ts",
+    "./dev": "./src/dev.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@junejs/core": "0.0.0",
+    "marked": "^18.0.5"
+  },
+  "peerDependencies": {
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "devDependencies": {
+    "rolldown": "^1.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/junebuild/june"
+  }
+}

package/src/app.ts

@@ -0,0 +1,155 @@
+// The dev server app: filesystem-driven discovery wired to the shared render
+// core (pipeline.ts). createApp() returns a Web-standard fetch(); the ONLY
+// dev-specific logic is the RouteResolver (walk app/, import the module, load
+// the layout chain) and the per-request trace wrapper. Everything else —
+// projections, discovery, document, layout wrapping — is the same code the
+// built worker runs, so dev and prod surfaces match by construction.
+//
+// CONFIG IS LOAD-BEARING: site name, agent flags, view transitions, speculation
+// all change observable output (test/config-output.test.ts) — the PoC shipped a
+// dev server that silently ignored june.config.ts for days.
+
+import { dirname, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import type { ComponentType } from "react";
+
+import { isRouteDefinition } from "@junejs/core/route";
+import { resolveAgent, resolveSpeculationRules, type JuneConfig } from "@junejs/core/config";
+import type { DocumentConfig } from "@junejs/core/document";
+import { runWithTrace, type RequestTrace } from "@junejs/core/instrumentation";
+
+import { findExtraFile, listRoutes, matchRouteTree, resolveNotFound, routeFiles, type SegmentMatch } from "./router";
+import { createPipeline, type ExtraHandler, type LayoutComponent, type Pipeline, type Resolved } from "./pipeline";
+import { memoizeResources } from "./resources";
+import { findClientEntry, bundleClientToString, CLIENT_SCRIPT_URL } from "./client-bundle";
+
+export type CreateAppOptions = {
+  appDir: string;
+  config?: JuneConfig;
+};
+
+export type JuneApp = {
+  fetch(request: Request): Promise<Response>;
+  // Import every route module once so defineAction() side effects register
+  // before the agent surface (discovery / mcp) is queried.
+  warmup(): Promise<void>;
+  routePaths(): Promise<string[]>;
+  earlyHints(): string[];
+};
+
+// Import a layout file's default export as a layout component (memoized).
+const layoutCache = new Map<string, LayoutComponent>();
+async function loadLayout(file: string): Promise<LayoutComponent | null> {
+  const cached = layoutCache.get(file);
+  if (cached) return cached;
+  const mod = (await import(pathToFileURL(file).href)) as { default?: LayoutComponent };
+  if (typeof mod.default !== "function") return null;
+  layoutCache.set(file, mod.default);
+  return mod.default;
+}
+
+async function loadChain(segments: SegmentMatch[]): Promise<LayoutComponent[]> {
+  const chain: LayoutComponent[] = [];
+  for (const seg of segments) {
+    if (!seg.layout) continue;
+    const L = await loadLayout(seg.layout);
+    if (L) chain.push(L);
+  }
+  return chain;
+}
+
+export function createApp({ appDir: appDirInput, config = {} }: CreateAppOptions): JuneApp {
+  // Normalize once: rolldown resolves the client entry against an absolute cwd,
+  // so a relative appDir would double the path. Absolute from here on.
+  const appDir = resolve(appDirInput);
+  const agent = resolveAgent(config.agent);
+  const speculation = config.speculation;
+  // app/_client.* present → the dev document loads /client.js and we serve it
+  // (bundled lazily, memoized). Detected the same way the build freezes it, so
+  // dev and built surfaces agree.
+  const clientEntry = findClientEntry(appDir);
+  const docConfig: DocumentConfig = {
+    site: config.site ?? {},
+    speculationRules: resolveSpeculationRules(speculation ?? undefined),
+    speculationDelivery: speculation ? speculation.delivery ?? "inline" : "inline",
+    viewTransitions: config.viewTransitions ?? true,
+    clientScript: clientEntry ? CLIENT_SCRIPT_URL : null,
+  };
+
+  let clientBundle: Promise<string> | undefined;
+  const serveClient = (): Promise<string> =>
+    // cwd = the app ROOT (appDir's parent) so rolldown resolves node_modules
+    // from the project, exactly like the build does.
+    (clientBundle ??= bundleClientToString(clientEntry!, dirname(appDir)));
+
+  const routePaths = () => listRoutes(appDir, { pageConvention: true });
+
+  const resources = memoizeResources(config.resources);
+
+  // The app's not-found.tsx is part of the dev surface too (the build freezes
+  // it into the manifest as `notFound`), and importing it is async — so the
+  // pipeline is built lazily on first fetch, memoized after.
+  let pipelinePromise: Promise<Pipeline> | undefined;
+  const getPipeline = (): Promise<Pipeline> => (pipelinePromise ??= buildPipeline());
+  async function buildPipeline(): Promise<Pipeline> {
+    const { notFound } = await resolveNotFound(appDir, "/");
+    let notFoundComponent: ComponentType<{ pathname: string }> | undefined;
+    if (notFound) {
+      const mod = (await import(pathToFileURL(notFound).href)) as { default?: unknown };
+      if (typeof mod.default === "function") {
+        notFoundComponent = mod.default as ComponentType<{ pathname: string }>;
+      }
+    }
+    let extra: ExtraHandler | undefined;
+    const extraFile = findExtraFile(appDir);
+    if (extraFile) {
+      const mod = (await import(pathToFileURL(extraFile).href)) as { default?: unknown };
+      if (typeof mod.default === "function") extra = mod.default as ExtraHandler;
+    }
+    return createPipeline({
+      extra,
+      docConfig,
+      agent,
+      routeList: routePaths,
+      earlyHints: config.earlyHints,
+      resources,
+      notFoundComponent,
+      resolve: async (pathname): Promise<Resolved | null> => {
+        const match = await matchRouteTree(appDir, pathname, { pageConvention: true });
+        if (!match) return null;
+        const mod = (await import(pathToFileURL(match.file).href)) as { default?: unknown };
+        if (!isRouteDefinition(mod.default)) return null;
+        return { def: mod.default, params: match.params, chain: await loadChain(match.segments) };
+      },
+    });
+  }
+
+  function newTrace(): RequestTrace {
+    return { id: crypto.randomUUID(), startedAt: performance.now(), events: [] };
+  }
+
+  return {
+    fetch(request) {
+      // Dev serves the islands runtime itself (build ships it as a static
+      // asset); bundled on first hit, memoized after.
+      if (clientEntry && new URL(request.url).pathname === CLIENT_SCRIPT_URL) {
+        return serveClient().then(
+          (code) =>
+            new Response(code, {
+              headers: { "content-type": "text/javascript; charset=utf-8" },
+            }),
+        );
+      }
+      return runWithTrace(newTrace(), async () => (await getPipeline()).fetch(request));
+    },
+    async warmup() {
+      for (const file of await routeFiles(appDir, { pageConvention: true })) {
+        await import(pathToFileURL(file).href).catch((err) => {
+          console.error(`[june] failed to load route ${file}`, err);
+        });
+      }
+    },
+    routePaths,
+    earlyHints: () => config.earlyHints ?? [],
+  };
+}

package/src/blob.ts

@@ -0,0 +1,99 @@
+// `blob` resource adapters — the object/file store seam (JuneBlob). The
+// zero-config dev default is a local directory; R2 (and S3-shaped backends) are
+// the deploy adapters. Same binding model as db/kv: declare `resources.blob` in
+// june.config.ts → injected as ctx.blob.
+
+import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+import type { BlobFactory, JuneBlob } from "@junejs/core/resources";
+
+// Keys come from app code (often user input) — reject path traversal / absolute
+// paths so a blob key can never escape the store directory.
+function safeKey(key: string): string {
+  if (key.startsWith("/") || key.split(/[\\/]/).includes("..")) {
+    throw new Error(`unsafe blob key: ${key}`);
+  }
+  return key;
+}
+
+function localBlobHandle(dir: string): JuneBlob {
+  return {
+    async get(key) {
+      const file = join(dir, safeKey(key)); // validate BEFORE the try, or the
+      try {
+        return new Uint8Array(await readFile(file)); // catch would swallow it
+      } catch {
+        return null;
+      }
+    },
+    async put(key, data) {
+      const file = join(dir, safeKey(key));
+      await mkdir(dirname(file), { recursive: true });
+      await writeFile(file, typeof data === "string" ? data : Buffer.from(data));
+    },
+    async delete(key) {
+      await rm(join(dir, safeKey(key)), { force: true });
+    },
+    async list(prefix = "") {
+      const out: string[] = [];
+      async function walk(d: string, base: string) {
+        let entries;
+        try {
+          entries = await readdir(d, { withFileTypes: true });
+        } catch {
+          return;
+        }
+        for (const e of entries) {
+          const rel = base ? `${base}/${e.name}` : e.name;
+          if (e.isDirectory()) await walk(join(d, e.name), rel);
+          else if (rel.startsWith(prefix)) out.push(rel);
+        }
+      }
+      await walk(dir, "");
+      return out.sort();
+    },
+  };
+}
+
+export function localBlob(opts: { dir?: string } = {}): BlobFactory {
+  const dir = opts.dir ?? ".june/blob";
+  return {
+    kind: "local",
+    open: async () => {
+      await mkdir(dir, { recursive: true });
+      return localBlobHandle(dir);
+    },
+  };
+}
+
+// --- R2 (Cloudflare) --------------------------------------------------------
+
+interface R2ObjectBody {
+  arrayBuffer(): Promise<ArrayBuffer>;
+}
+export interface R2Bucket {
+  get(key: string): Promise<R2ObjectBody | null>;
+  put(key: string, data: ArrayBuffer | Uint8Array | string): Promise<unknown>;
+  delete(key: string): Promise<void>;
+  list(opts?: { prefix?: string }): Promise<{ objects: { key: string }[] }>;
+}
+
+export function r2(bucket: R2Bucket): BlobFactory {
+  const handle: JuneBlob = {
+    async get(key) {
+      const obj = await bucket.get(key);
+      return obj ? new Uint8Array(await obj.arrayBuffer()) : null;
+    },
+    async put(key, data) {
+      await bucket.put(key, data);
+    },
+    async delete(key) {
+      await bucket.delete(key);
+    },
+    async list(prefix) {
+      return (await bucket.list({ prefix })).objects.map((o) => o.key);
+    },
+  };
+  return { kind: "r2", open: async () => handle };
+}