@junejs/server 0.0.2

package/src/deploy.ts

@@ -0,0 +1,72 @@
+// `june deploy` — ship a June app. Workers target (v1).
+//
+// The verb is fixed, the target is an adapter (same seam philosophy as
+// JuneHost): today this orchestrates `june build` + wrangler (which owns auth,
+// wasm/ttf rules, and the upload API); a future "june-cloud" target swaps the
+// adapter, not the CLI. --dry-run is the CI test (build + wrangler validate,
+// no upload).
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+import { juneBuild } from "./build";
+import { loadJuneConfig } from "./config-loader";
+
+export type DeployResult = {
+  url: string | null;
+  dryRun: boolean;
+  configPath: string;
+};
+
+export async function juneDeploy(
+  appRoot: string,
+  options: { dryRun?: boolean; skipBuild?: boolean } = {},
+): Promise<DeployResult> {
+  const cfg = await loadJuneConfig(appRoot);
+  const target = cfg.deploy?.target ?? "workers";
+  if (target !== "workers") throw new Error(`unknown deploy target: ${target}`);
+
+  if (!options.skipBuild) {
+    const built = await juneBuild(appRoot);
+    console.log(`built ${built.outFile}`);
+  }
+
+  // The app's own wrangler config wins; otherwise the one `june build` emits next
+  // to the bundle (its `main` is relative to the config file).
+  const configPath =
+    [join(appRoot, "wrangler.toml"), join(appRoot, "wrangler.jsonc")].find(existsSync) ??
+    join(appRoot, "dist/wrangler.jsonc");
+  if (!existsSync(configPath)) {
+    throw new Error(`no wrangler config found (expected ${configPath}) — run june build first`);
+  }
+
+  if (!options.dryRun && !process.env.CLOUDFLARE_API_TOKEN) {
+    console.log(
+      "note: CLOUDFLARE_API_TOKEN not set — wrangler will fall back to its own login\n" +
+        "      (run `bunx wrangler login` once, or export the token).",
+    );
+  }
+
+  // Pinned: assets-mode needs wrangler ≥4.99 (reminder #7).
+  const args = ["bunx", "wrangler@4.99.0", "deploy", "--config", configPath];
+  if (options.dryRun) args.push("--dry-run");
+
+  const proc = Bun.spawn(args, { cwd: appRoot, stdout: "pipe", stderr: "pipe" });
+  const [out, err, code] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  if (out.trim()) console.log(out.trimEnd());
+  if (code !== 0) {
+    if (/authentication|login|10000/i.test(err + out)) {
+      throw new Error(
+        "wrangler authentication failed — set CLOUDFLARE_API_TOKEN or run `bunx wrangler login`.\n" +
+          err.trim(),
+      );
+    }
+    throw new Error(`wrangler deploy failed (exit ${code})\n${err.trim()}`);
+  }
+
+  const url = out.match(/https:\/\/\S+\.workers\.dev\S*/)?.[0] ?? null;
+  return { url, dryRun: options.dryRun ?? false, configPath };
+}

package/src/dev-reload.ts

@@ -0,0 +1,77 @@
+// Dev live-reload — the browser half of the watch story. The supervisor
+// (cli watch.ts) restarts the SERVER on save; this module makes the BROWSER
+// follow: every dev HTML page gets a tiny script that holds an SSE connection
+// to /__june/events. A restart drops the connection; the script reconnects
+// and reloads on success. No version tokens, no diffing — the dropped socket
+// IS the signal, which is exactly right for a process-restart reload model.
+//
+// This lives in the startDevServer WRAPPER, never in the pipeline: dev/built
+// parity (parity.test.ts compares pipeline outputs byte-for-byte) stays
+// untouched, and nothing here can leak into a build.
+
+const EVENTS_PATH = "/__june/events";
+const SCRIPT_PATH = "/__june/reload.js";
+
+const RELOAD_JS = `// june dev live-reload: reconnect-after-drop → location.reload()
+(() => {
+  let dropped = false;
+  const connect = () => {
+    const es = new EventSource(${JSON.stringify(EVENTS_PATH)});
+    es.addEventListener("open", () => {
+      if (dropped) location.reload();
+      dropped = false;
+    });
+    es.addEventListener("error", () => {
+      dropped = true;
+      // EventSource auto-retries while the connection is flaky, but goes to
+      // CLOSED (and stays there) on hard failures like a refused connection
+      // mid-restart — recreate it ourselves in that case.
+      if (es.readyState === EventSource.CLOSED) {
+        es.close();
+        setTimeout(connect, 300);
+      }
+    });
+  };
+  connect();
+})();
+`;
+
+function devEvents(): Response {
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      // One greeting so the browser fires `open`; then the socket just stays
+      // up until this process dies — the restart is the next event.
+      controller.enqueue(new TextEncoder().encode("retry: 300\n\ndata: connected\n\n"));
+    },
+  });
+  return new Response(stream, {
+    headers: { "content-type": "text/event-stream", "cache-control": "no-store" },
+  });
+}
+
+// Wrap the app's fetch: answer the two dev endpoints, and inject the reload
+// script into every HTML document on its way out.
+export function withLiveReload(
+  fetchApp: (req: Request) => Promise<Response>,
+): (req: Request) => Promise<Response> {
+  return async (req) => {
+    const { pathname } = new URL(req.url);
+    if (pathname === EVENTS_PATH) return devEvents();
+    if (pathname === SCRIPT_PATH) {
+      return new Response(RELOAD_JS, {
+        headers: { "content-type": "text/javascript; charset=utf-8", "cache-control": "no-store" },
+      });
+    }
+
+    const res = await fetchApp(req);
+    if (!res.headers.get("content-type")?.includes("text/html")) return res;
+    // Dev HTML is fully buffered by the pipeline already (allReady), so a
+    // text() round-trip costs nothing.
+    const html = await res.text();
+    const tag = `<script src="${SCRIPT_PATH}" defer></script>`;
+    const injected = html.includes("</body>") ? html.replace("</body>", `${tag}</body>`) : html + tag;
+    const headers = new Headers(res.headers);
+    headers.delete("content-length"); // the body just grew; let the host recompute
+    return new Response(injected, { status: res.status, headers });
+  };
+}

package/src/dev.ts

@@ -0,0 +1,41 @@
+// `june dev` — wire the request pipeline to a host and listen.
+//
+// Steps: install the async-context provider (so tracing + cache auto-tagging
+// work), load june.config.ts from the app root (the config the PoC forgot to
+// read), build the app, and serve through the detected JuneHost.
+
+import { loadJuneConfig } from "./config-loader";
+import { installAsyncContext } from "./instrumentation";
+import { createApp } from "./app";
+import { withLiveReload } from "./dev-reload";
+import { host as defaultHost, type JuneHost, type ServeHandle } from "./host";
+
+export type DevServerOptions = {
+  appDir: string;
+  port?: number;
+  host?: JuneHost;
+};
+
+export type DevServer = ServeHandle & { url: string };
+
+export async function startDevServer({
+  appDir,
+  port = 3000,
+  host = defaultHost,
+}: DevServerOptions): Promise<DevServer> {
+  await installAsyncContext();
+  const config = await loadJuneConfig(appDir);
+  const app = createApp({ appDir, config });
+  await app.warmup();
+
+  // Live reload wraps the DEV SERVER only — the pipeline (and therefore
+  // dev/built parity) never sees it. See dev-reload.ts.
+  const handle = host.serve(withLiveReload((req) => app.fetch(req)), {
+    port,
+    earlyHints: () => app.earlyHints(),
+  });
+
+  const url = `http://localhost:${handle.port}`;
+  console.log(`june dev → ${url}  (host: ${host.name})`);
+  return { ...handle, url };
+}

package/src/host.ts

@@ -0,0 +1,234 @@
+// The HOST INTERFACE — the seam between June's portable core and the JS runtime
+// it runs on. The core speaks Web standards (Request/Response/ReadableStream/
+// crypto) plus THIS object for the few things standards don't cover: binding a
+// port, spawning the react-server Flight subprocess, and the database.
+//
+// A new deploy target (Workers, creekd, Vercel) is a new implementation of this
+// interface, not a change to the framework. This package is the HOST layer —
+// static `node:*` imports are fine here (Bun implements the node: builtins too);
+// it is the pure `@junejs/core` package, never this one, that must stay node-free.
+//
+// ASYNC-FIRST DB (the deliberate redesign): the PoC shipped a SYNCHRONOUS
+// SqliteDb surface — and that was the one dead end. D1 and every edge database
+// are async; an API that returns rows synchronously cannot be implemented on
+// them without blocking or buffering hacks. So `JuneDb` is async from day one;
+// the Bun/Node SQLite drivers (which happen to be sync) are wrapped, and D1
+// (Phase 5) implements the same interface natively.
+
+import { spawn } from "node:child_process";
+import { createServer } from "node:http";
+import { Readable } from "node:stream";
+
+// The JuneDb / RunResult CONTRACT now lives in the pure @junejs/core layer
+// (@junejs/core/resources) so any ORM can target it. Re-exported here for callers
+// that still import from the host.
+import type { JuneDb, RunResult } from "@junejs/core/resources";
+export type { JuneDb, RunResult };
+
+export type ServeHandle = { port: number; stop(force?: boolean): void };
+
+export type SpawnedModule = {
+  stdout: ReadableStream<Uint8Array>;
+  stderrText(): Promise<string>;
+  exited: Promise<number>;
+};
+
+export interface JuneHost {
+  readonly name: "bun" | "node";
+  serve(
+    handler: (req: Request) => Promise<Response>,
+    opts: { port: number; earlyHints?: () => string[] },
+  ): ServeHandle;
+  // Spawn a module in a child runtime (the react-server Flight renderer, which
+  // must run under a different module-resolution condition). Phase 4 supersedes
+  // this with the in-isolate dual-graph loader; the seam stays for the fallback.
+  spawnModule(entry: string, args: string[], opts: { conditions?: string[] }): SpawnedModule;
+  // Open a LOCAL SQLite database — the internal primitive the `sqlite()` db
+  // adapter builds on (docs/data-layer-boundary.md: openDb is demoted from the
+  // user-facing API to a host primitive; apps declare `resources.db` instead).
+  openDb(path: string): Promise<JuneDb>;
+}
+
+// --- a tiny sync→async SQLite adapter shared by both hosts ------------------
+
+// The shape bun:sqlite exposes directly and node:sqlite is adapted to: a
+// prepared statement with positional binding.
+type SyncStatement = {
+  all(...params: unknown[]): unknown[];
+  get(...params: unknown[]): unknown;
+  run(...params: unknown[]): { changes: number | bigint; lastInsertRowid?: number | bigint };
+};
+type SyncSqlite = {
+  query(sql: string): SyncStatement;
+  exec(sql: string): void;
+  close(): void;
+};
+
+// Wrap a synchronous SQLite handle as the async JuneDb. The driver work is
+// synchronous, but the SURFACE is async, so swapping in D1 later is invisible
+// to every caller.
+function asyncSqlite(db: SyncSqlite): JuneDb {
+  const self: JuneDb = {
+    async query<T>(sql: string, params: unknown[] = []) {
+      return db.query(sql).all(...params) as T[];
+    },
+    async get<T>(sql: string, params: unknown[] = []) {
+      // Normalize "no row" to undefined — bun:sqlite returns null, node:sqlite
+      // returns undefined; the seam hides the difference.
+      return (db.query(sql).get(...params) ?? undefined) as T | undefined;
+    },
+    async run(sql: string, params: unknown[] = []) {
+      const r = db.query(sql).run(...params);
+      return { changes: Number(r.changes), lastInsertRowid: r.lastInsertRowid ?? 0 };
+    },
+    async exec(sql: string) {
+      db.exec(sql);
+    },
+    async transaction<T>(fn: (tx: JuneDb) => Promise<T>) {
+      db.exec("BEGIN");
+      try {
+        const out = await fn(self); // same connection — sqlite is single-writer
+        db.exec("COMMIT");
+        return out;
+      } catch (e) {
+        db.exec("ROLLBACK");
+        throw e;
+      }
+    },
+    async close() {
+      db.close();
+    },
+  };
+  return self;
+}
+
+// --- Bun host ---------------------------------------------------------------
+
+function bunHost(): JuneHost {
+  return {
+    name: "bun",
+    serve(handler, opts) {
+      const server = Bun.serve({ port: opts.port, fetch: handler });
+      return { port: server.port ?? opts.port, stop: (force) => void server.stop(force) };
+    },
+    spawnModule(entry, args, opts) {
+      const cmd = [
+        "bun",
+        ...(opts.conditions ?? []).flatMap((c) => ["--conditions", c]),
+        entry,
+        ...args,
+      ];
+      const child = Bun.spawn({ cmd, cwd: process.cwd(), stdout: "pipe", stderr: "pipe" });
+      return {
+        stdout: child.stdout,
+        stderrText: () => new Response(child.stderr).text(),
+        exited: child.exited,
+      };
+    },
+    async openDb(path) {
+      // Non-literal specifier: only Bun has bun:sqlite, so resolve it at runtime.
+      const specifier = "bun:sqlite";
+      const { Database } = (await import(specifier)) as {
+        Database: new (p: string, o?: { create?: boolean }) => SyncSqlite;
+      };
+      return asyncSqlite(new Database(path, { create: true }));
+    },
+  };
+}
+
+// --- Node host --------------------------------------------------------------
+
+function nodeHost(): JuneHost {
+  return {
+    name: "node",
+    serve(handler, opts) {
+      const server = createServer(async (req, res) => {
+        try {
+          // Real 103 Early Hints (RFC 8297) for document requests — the browser
+          // starts fetching critical assets while we render. Node-host exclusive
+          // (Bun.serve has no interim-response API; CF reads the Link header).
+          const hints = opts.earlyHints?.();
+          if (
+            hints?.length &&
+            req.method === "GET" &&
+            (req.headers.accept ?? "").includes("text/html")
+          ) {
+            res.writeEarlyHints({ link: hints });
+          }
+          const url = `http://${req.headers.host ?? "localhost"}${req.url ?? "/"}`;
+          const hasBody = req.method !== "GET" && req.method !== "HEAD";
+          const request = new Request(url, {
+            method: req.method,
+            headers: req.headers as Record<string, string>,
+            body: hasBody ? (Readable.toWeb(req) as unknown as BodyInit) : undefined,
+            // @ts-expect-error half-duplex is required for streamed request bodies
+            duplex: "half",
+          });
+          const response = await handler(request);
+          res.writeHead(response.status, Object.fromEntries(response.headers.entries()));
+          if (response.body) {
+            Readable.fromWeb(response.body as never).pipe(res);
+          } else {
+            res.end();
+          }
+        } catch (err) {
+          console.error("[june:node] request failed", err);
+          if (!res.headersSent) res.writeHead(500);
+          res.end("Internal Server Error");
+        }
+      });
+      server.listen(opts.port);
+      return {
+        get port() {
+          const addr = server.address();
+          return typeof addr === "object" && addr ? addr.port : opts.port;
+        },
+        stop(force) {
+          server.close();
+          if (force) server.closeAllConnections?.();
+        },
+      };
+    },
+    spawnModule(entry, args, opts) {
+      const child = spawn(
+        process.execPath,
+        [
+          "--import",
+          "tsx", // TS-on-Node for the fallback path; `june build` emits dist JS
+          ...(opts.conditions ?? []).flatMap((c) => ["--conditions", c]),
+          entry,
+          ...args,
+        ],
+        { cwd: process.cwd(), stdio: ["ignore", "pipe", "pipe"] },
+      );
+      const errChunks: Buffer[] = [];
+      child.stderr.on("data", (c: Buffer) => errChunks.push(c));
+      return {
+        stdout: Readable.toWeb(child.stdout) as unknown as ReadableStream<Uint8Array>,
+        stderrText: async () => Buffer.concat(errChunks).toString(),
+        exited: new Promise((resolve) => child.on("exit", (code) => resolve(code ?? 0))),
+      };
+    },
+    async openDb(path) {
+      const specifier = "node:sqlite"; // node-only builtin; resolve at runtime
+      const { DatabaseSync } = (await import(specifier)) as {
+        DatabaseSync: new (p: string) => {
+          prepare(sql: string): SyncStatement;
+          exec(sql: string): void;
+          close(): void;
+        };
+      };
+      const db = new DatabaseSync(path);
+      // Adapt node:sqlite (prepare()) to the query()-shaped SyncSqlite surface.
+      return asyncSqlite({
+        query: (sql) => db.prepare(sql),
+        exec: (sql) => db.exec(sql),
+        close: () => db.close(),
+      });
+    },
+  };
+}
+
+// bun-types declares the global `Bun`; on Node the binding doesn't exist at
+// runtime, which is exactly what the typeof guard checks.
+export const host: JuneHost = typeof Bun !== "undefined" ? bunHost() : nodeHost();

package/src/index.ts

@@ -0,0 +1,42 @@
+// @junejs/server — June's host adapters + dev server. Host-coupled (`node:*`
+// allowed); it composes ON TOP of the pure `@junejs/core` contract layer.
+
+export { host, type JuneHost, type JuneDb, type RunResult, type ServeHandle, type SpawnedModule } from "./host";
+export { sqlite, d1, type D1Database } from "./db";
+export { memoryKv, redisKv } from "./kv";
+export { localBlob, r2, type R2Bucket } from "./blob";
+export { memoizeResources } from "./resources";
+export { loadJuneConfig } from "./config-loader";
+export { collection, entry, type ContentEntry } from "./content";
+export {
+  listRoutes,
+  matchRoute,
+  matchRouteTree,
+  resolveNotFound,
+  type RouteMatch,
+  type RouteTreeMatch,
+  type SegmentMatch,
+  type MatchOptions,
+} from "./router";
+export { installAsyncContext } from "./instrumentation";
+export { negotiate, type Negotiated } from "./negotiate";
+export {
+  createPipeline,
+  type Pipeline,
+  type PipelineConfig,
+  type RouteResolver,
+  type Resolved,
+  type LayoutComponent,
+} from "./pipeline";
+export { createApp, type JuneApp, type CreateAppOptions } from "./app";
+export { createWorker, type WorkerManifest } from "./worker";
+export {
+  juneBuild,
+  buildManifest,
+  scanRoutes,
+  generateContent,
+  freezeConfig,
+  type BuildResult,
+} from "./build";
+export { juneDeploy, type DeployResult } from "./deploy";
+export { startDevServer, type DevServer, type DevServerOptions } from "./dev";

package/src/instrumentation.ts

@@ -0,0 +1,33 @@
+// The host side of request tracing. @junejs/core's instrumentation is pure and
+// host-free — it exposes `installTraceContext(provider)` and otherwise no-ops.
+// This module supplies the provider: node:async_hooks' AsyncLocalStorage,
+// loaded LAZILY through a non-literal specifier so no bundler resolves `node:*`
+// (workerd assets-mode registers chunks raw — a static import would break
+// module registration even on a path that never runs there). See rebuild-plan
+// reminders #1 and #4.
+//
+// Hosts that lack async_hooks simply never call this; @junejs/core then runs
+// untraced and every recorder degrades to a no-op — requests still serve.
+
+import { installTraceContext, type RequestTrace } from "@junejs/core/instrumentation";
+
+let installed = false;
+
+export async function installAsyncContext(): Promise<boolean> {
+  if (installed) return true;
+  try {
+    const specifier = "node:async_hooks";
+    const mod = (await import(specifier)) as {
+      AsyncLocalStorage: new () => {
+        getStore(): RequestTrace | undefined;
+        run<R>(store: RequestTrace, fn: () => R): R;
+      };
+    };
+    installTraceContext(new mod.AsyncLocalStorage());
+    installed = true;
+    return true;
+  } catch {
+    // No async context on this host — tracing stays disabled.
+    return false;
+  }
+}

package/src/kv.ts

@@ -0,0 +1,34 @@
+// `kv` resource adapters. The kv resource IS the cache (docs/data-layer-boundary
+// .md: "reframe cache as the kv resource — it already is one"): these wrap
+// @junejs/core/cache's CacheStore (memory / redis) as the simpler JuneKv contract,
+// so there is ONE key-value system, surfaced both as cache() and as ctx.kv.
+
+import { memory, redis, type CacheStore } from "@junejs/core/cache";
+import type { JuneKv, KvFactory } from "@junejs/core/resources";
+
+function kvOver(store: CacheStore): JuneKv {
+  return {
+    async get<T>(key: string) {
+      const entry = await store.get(key);
+      return (entry?.value ?? null) as T | null;
+    },
+    async put(key: string, value: unknown, opts?: { ttl?: number }) {
+      const expiresAt = opts?.ttl ? Date.now() + opts.ttl * 1000 : null;
+      await store.set(key, { value, expiresAt, staleUntil: expiresAt, tags: [] });
+    },
+    async delete(key: string) {
+      await store.delete(key);
+    },
+  };
+}
+
+// In-memory kv — the zero-config dev default (same store class cache() uses).
+export function memoryKv(): KvFactory {
+  return { kind: "memory", open: async () => kvOver(await memory().connect()) };
+}
+
+// Redis-backed kv (Bun's native client) — and the shape a Cloudflare KV adapter
+// slots into (same JuneKv contract).
+export function redisKv(opts: { url: string }): KvFactory {
+  return { kind: "redis", open: async () => kvOver(await redis(opts).connect()) };
+}

package/src/negotiate.ts

@@ -0,0 +1,57 @@
+// Content negotiation — turn a request into (RenderTarget, clean pathname,
+// speculative?). Pure and host-free so it is trivially testable; the dev server
+// and the built worker both route through it, so the negotiation can't drift.
+//
+// Precedence: an explicit URL extension (`/users.json`) wins over the Accept
+// header — a link is unambiguous; Accept is a hint. The clean pathname (with
+// the projection extension stripped) is what the router matches.
+
+import type { RenderTarget } from "@junejs/core/route";
+
+const EXT_TARGET: Record<string, RenderTarget> = {
+  ".json": "json",
+  ".agent": "agent",
+  ".md": "md",
+};
+
+const ACCEPT_TARGET: Array<[test: RegExp, target: RenderTarget]> = [
+  [/application\/vnd\.june-agent\+json/, "agent"],
+  [/text\/markdown/, "md"],
+  [/application\/json/, "json"],
+];
+
+export type Negotiated = {
+  target: RenderTarget;
+  pathname: string; // projection extension stripped
+  speculative: boolean;
+};
+
+export function negotiate(url: URL, request: Request): Negotiated {
+  let pathname = url.pathname;
+  let target: RenderTarget | null = null;
+
+  for (const [ext, t] of Object.entries(EXT_TARGET)) {
+    if (pathname.endsWith(ext)) {
+      target = t;
+      pathname = pathname.slice(0, -ext.length) || "/";
+      break;
+    }
+  }
+
+  if (!target) {
+    const accept = request.headers.get("accept") ?? "";
+    for (const [re, t] of ACCEPT_TARGET) {
+      if (re.test(accept)) {
+        target = t;
+        break;
+      }
+    }
+  }
+
+  // A speculative request (Sec-Purpose: prefetch / prerender) may never be seen
+  // — load()s read it to skip side effects (analytics, rate limits, counters).
+  const purpose = request.headers.get("sec-purpose") ?? "";
+  const speculative = /prefetch|prerender/.test(purpose);
+
+  return { target: target ?? "view", pathname, speculative };
+}