@junejs/core 0.0.2

package/src/mcp.ts

@@ -0,0 +1,116 @@
+// MCP server — projects the unified action registry as MCP tools over a
+// Web-Standards (Request -> Response) handler, mounted at /mcp.
+//
+// Why a hand-rolled handler instead of the official SDK's server transport:
+// `@modelcontextprotocol/sdk`'s StreamableHTTPServerTransport is Node-coupled
+// (node:http IncomingMessage/ServerResponse), which breaks June's
+// Web-Standards + Cloudflare story. The protocol surface we need (initialize,
+// tools/list, tools/call) is small and stateless, so we implement it directly
+// against the Streamable HTTP shape — identical on the native runtime and on
+// Workers. (The SDK is still used client-side to verify spec compliance.)
+
+import { ACTION_REGISTRY, invokeAction } from "./agent";
+import type { ActionContext } from "./context";
+
+const PROTOCOL_VERSION = "2025-06-18";
+
+type Rpc = {
+  jsonrpc: "2.0";
+  id?: string | number | null;
+  method?: string;
+  params?: Record<string, unknown>;
+};
+
+function ok(id: Rpc["id"], result: unknown) {
+  return { jsonrpc: "2.0" as const, id, result };
+}
+
+function err(id: Rpc["id"], code: number, message: string) {
+  return { jsonrpc: "2.0" as const, id, error: { code, message } };
+}
+
+// Only rich actions (with a description) are surfaced as MCP tools; bare RSC
+// server actions registered via action(fn, id) carry no schema.
+function tools() {
+  return [...ACTION_REGISTRY.values()]
+    .filter((action) => action.description)
+    .map((action) => ({
+      name: action.id,
+      description: action.description,
+      inputSchema: action.input,
+    }));
+}
+
+async function handle(message: Rpc, ctx: ActionContext): Promise<object | null> {
+  const { id, method, params } = message;
+  // Notifications (no id) get no response.
+  if (id === undefined || id === null) return null;
+
+  switch (method) {
+    case "initialize":
+      return ok(id, {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: { tools: { listChanged: false } },
+        serverInfo: { name: "june", version: "0.0.0" },
+      });
+    case "ping":
+      return ok(id, {});
+    case "tools/list":
+      return ok(id, { tools: tools() });
+    case "tools/call": {
+      const name = params?.name as string | undefined;
+      const args = (params?.arguments as Record<string, unknown>) ?? {};
+      if (!name) return err(id, -32602, "Missing tool name");
+      try {
+        // The agent's tool call runs through the SAME ctx (principal + resources)
+        // the UI uses — one authorization model for both.
+        const result = await invokeAction(name, args, ctx);
+        return ok(id, {
+          content: [{ type: "text", text: JSON.stringify(result) }],
+        });
+      } catch (error) {
+        return ok(id, {
+          content: [{ type: "text", text: String(error) }],
+          isError: true,
+        });
+      }
+    }
+    default:
+      return err(id, -32601, `Method not found: ${method}`);
+  }
+}
+
+// ctx (principal + resources) is injected by the host (the pipeline) so an
+// agent's tool call runs under the same authorization as the UI. Defaults to {}
+// for hosts/tests without one.
+export async function mcpHandler(request: Request, ctx: ActionContext = {}): Promise<Response> {
+  if (request.method !== "POST") {
+    return new Response("MCP endpoint — POST JSON-RPC (Streamable HTTP)", {
+      status: 405,
+      headers: { allow: "POST" },
+    });
+  }
+
+  let body: unknown;
+  try {
+    body = await request.json();
+  } catch {
+    return Response.json(err(null, -32700, "Parse error"), { status: 400 });
+  }
+
+  const headers = { "mcp-protocol-version": PROTOCOL_VERSION };
+
+  if (Array.isArray(body)) {
+    const responses = (await Promise.all(body.map((m) => handle(m as Rpc, ctx)))).filter(
+      Boolean,
+    );
+    return responses.length
+      ? Response.json(responses, { headers })
+      : new Response(null, { status: 202, headers });
+  }
+
+  const response = await handle(body as Rpc, ctx);
+  return response
+    ? Response.json(response, { headers })
+    : new Response(null, { status: 202, headers });
+}

package/src/resources.ts

@@ -0,0 +1,73 @@
+// The data RESOURCE contract — the seam the framework depends on, NOT an ORM.
+// PURE and host-free: these are type-only declarations (Promises, Web types), no
+// `node:*`, no driver. The implementations (sqlite/d1/postgres, local/r2/s3,
+// memory/redis) live in @junejs/server's adapters and behind them, Juno; this
+// layer only names the contract so RouteContext can carry injected handles and
+// any ORM can target the same shape. See docs/data-layer-boundary.md.
+
+// --- db (relational / SQL) --------------------------------------------------
+
+export type RunResult = { changes: number; lastInsertRowid: number | bigint };
+
+// The async database surface. SELECT → query()/get(); writes → run(); DDL or
+// multi-statement scripts → exec(). Async from day one so D1/edge slot in behind
+// the same interface (the PoC's sync surface was the one dead end).
+export interface JuneDb {
+  query<T = unknown>(sql: string, params?: unknown[]): Promise<T[]>;
+  get<T = unknown>(sql: string, params?: unknown[]): Promise<T | undefined>;
+  run(sql: string, params?: unknown[]): Promise<RunResult>;
+  exec(sql: string): Promise<void>;
+  transaction<T>(fn: (tx: JuneDb) => Promise<T>): Promise<T>;
+  close(): Promise<void>;
+}
+
+// --- kv (key-value / cache) -------------------------------------------------
+
+export interface JuneKv {
+  get<T = unknown>(key: string): Promise<T | null>;
+  put(key: string, value: unknown, opts?: { ttl?: number }): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+
+// --- blob (object / file) ---------------------------------------------------
+
+export interface JuneBlob {
+  get(key: string): Promise<Uint8Array | null>;
+  put(key: string, data: Uint8Array | string): Promise<void>;
+  delete(key: string): Promise<void>;
+  list(prefix?: string): Promise<string[]>;
+}
+
+// --- factories (declared in june.config.ts; opened by the host) -------------
+// Same shape as the cache CacheStoreFactory: a `kind` tag + an async open. The
+// factory is abstract (pure); the concrete adapter (sqlite/d1/local/r2/...) is
+// host code that implements the handle.
+
+export interface DbFactory {
+  readonly kind: string;
+  open(): Promise<JuneDb>;
+}
+export interface KvFactory {
+  readonly kind: string;
+  open(): Promise<JuneKv>;
+}
+export interface BlobFactory {
+  readonly kind: string;
+  open(): Promise<JuneBlob>;
+}
+
+// What june.config.ts declares under `resources`. Omit one and it never exists
+// (not instantiated, not bundled, compiled away for static apps).
+export type ResourceConfig = {
+  db?: DbFactory;
+  kv?: KvFactory;
+  blob?: BlobFactory;
+};
+
+// The opened handles, injected onto RouteContext by the host. Each is present
+// only when the matching resource was declared.
+export type Resources = {
+  db?: JuneDb;
+  kv?: JuneKv;
+  blob?: JuneBlob;
+};

package/src/route.ts

@@ -0,0 +1,122 @@
+// route() — a single route definition that feeds one `load()` into multiple
+// content-negotiated projections.
+//
+//   export default route({
+//     async load(ctx) { return { users: await Users.all() }; },
+//     view({ users })  { return <UsersPage users={users} />; },  // HTML / Flight
+//     json({ users })  { return { users }; },                    // data API
+//     agent({ users }) { return manifest.resource("users", users); },
+//   });
+//
+// The same data, three representations, never drifting apart. `view` is the
+// React projection (named `view`, not `html`, because the framework decides
+// HTML-SSR vs RSC Flight by negotiation). `json` is the plain data API. `agent`
+// is the capability-described resource for agent clients.
+
+import type { JuneDb, JuneKv, JuneBlob } from "./resources";
+import type { Principal, Session } from "./context";
+
+export type RenderTarget = "view" | "json" | "agent" | "md";
+
+// Per-route document metadata. Static metadata keeps the streaming shell;
+// a FUNCTION (deriving from load() data) forces an eager load — the <head>
+// streams first, so dynamic metadata costs the loading-boundary for that
+// route. Choose per route.
+export type Metadata = {
+  title?: string;
+  description?: string;
+  canonical?: string;
+  robots?: string; // e.g. "noindex"
+  openGraph?: {
+    title?: string;
+    description?: string;
+    image?: string;
+    type?: string; // "website" | "article" | ...
+  };
+};
+
+export type RouteContext<
+  TParams extends Record<string, string> = Record<string, string>,
+> = {
+  request: Request;
+  url: URL;
+  params: TParams;
+  target: RenderTarget;
+  // True when the request is SPECULATIVE (Sec-Purpose: prefetch / prerender):
+  // the page may never be seen. Skip side effects — view counters, analytics,
+  // rate-limit consumption. (Client-side twin: defer pageviews until
+  // !document.prerendering.)
+  speculative?: boolean;
+  // Resource handles injected by the host (the binding model), present only when
+  // declared in june.config.ts `resources`. The framework depends on these
+  // contracts, never on a specific ORM — see docs/data-layer-boundary.md.
+  db?: JuneDb;
+  kv?: JuneKv;
+  blob?: JuneBlob;
+  // The authenticated principal, populated by the auth integration off the
+  // request (undefined until @junejs/auth is wired). Routes gate on ctx.user;
+  // the SAME principal reaches actions via ActionContext.
+  user?: Principal;
+  session?: Session;
+};
+
+export type RouteCache = {
+  ttl?: number; // seconds; omit for no expiry (tag-invalidated only)
+  swr?: number; // extra stale-while-revalidate window, seconds (needs ttl)
+  tags?: string[]; // a mutation calling invalidate(tag) drops this route's cache
+};
+
+export type RouteDefinition<TData = unknown> = {
+  load?: (ctx: RouteContext) => TData | Promise<TData>;
+  view?: (data: TData, ctx: RouteContext) => React.ReactNode;
+  json?: (data: TData, ctx: RouteContext) => unknown | Promise<unknown>;
+  agent?: (data: TData, ctx: RouteContext) => unknown | Promise<unknown>;
+  // Markdown projection. If absent, the `md` target is auto-derived from `json`.
+  md?: (data: TData, ctx: RouteContext) => string | Promise<string>;
+  // Response cache: cache the rendered output of GET requests, keyed by
+  // target+URL, dropped by tag invalidation. Uses @junejs/core/cache.
+  cache?: RouteCache;
+  // `june build` renders this route's projections (html/md/json) to static
+  // files served by the Workers assets layer BEFORE the worker runs (0ms).
+  // Static routes only; opt-in because it freezes per-request behavior.
+  prerender?: boolean;
+  // Document metadata for the view projection (title/description/OG/...).
+  metadata?: Metadata | ((data: TData, ctx: RouteContext) => Metadata);
+};
+
+const ROUTE_BRAND = Symbol.for("june.route");
+
+export type BrandedRoute<TData = unknown> = RouteDefinition<TData> & {
+  [ROUTE_BRAND]: true;
+};
+
+export function route<TData>(def: RouteDefinition<TData>): BrandedRoute<TData> {
+  return { ...def, [ROUTE_BRAND]: true };
+}
+
+export function isRouteDefinition(value: unknown): value is BrandedRoute {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as Record<symbol, unknown>)[ROUTE_BRAND] === true
+  );
+}
+
+// The order each requested target degrades through when a projection is absent.
+// An agent asking for /users.agent on a route with no `agent()` still gets the
+// JSON projection rather than a 406.
+const FALLBACK: Record<RenderTarget, RenderTarget[]> = {
+  agent: ["agent", "json", "view"],
+  json: ["json", "agent", "view"],
+  view: ["view", "json", "agent"],
+  // `md` is handled specially (auto-derived from json when md() is absent);
+  // this entry is only the last-resort fall-through.
+  md: ["md", "json", "view"],
+};
+
+export function resolveProjection(
+  def: BrandedRoute,
+  requested: RenderTarget,
+): RenderTarget {
+  return FALLBACK[requested].find((t) => typeof def[t] === "function") ?? "view";
+}