@junejs/core 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,20 @@
+# @junejs/core
+
+The agent-native React framework. This package is the **pure, host-free
+contract layer** — the most stable artifacts of the design, with zero `node:*`
+or `Bun.*` (enforced by `test/purity.test.ts`).
+
+| Subpath | What |
+| --- | --- |
+| `@junejs/core/route` | `route()` + content-negotiated projections (view/json/agent/md) |
+| `@junejs/core/config` | config schema + pure resolvers (`defineJune`, `resolveAgent`, speculation rules) |
+| `@junejs/core/document` | the shared HTML shell — one document drives dev + built worker (charset lives here) |
+| `@junejs/core/agent` | the unified action registry: `defineAction`, `manifest`, `invokeAction` |
+| `@junejs/core/discovery` | llms.txt (with the canonical-names stanza), sitemap, api-catalog, MCP card, Link header |
+| `@junejs/core/mcp` | the Web-standard MCP endpoint (`mcpHandler`) |
+| `@junejs/core/cache` | `cache()` / `invalidate()` + the `CacheStore` seam (memory built in) |
+| `@junejs/core/instrumentation` | request tracing; the host installs the async-context provider |
+
+Host-coupled concerns (fs config loader, content pipeline, dev server,
+build/deploy, data layer) live in later layers and import *from* here — never
+the other way around.

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@junejs/core",
+  "version": "0.0.2",
+  "description": "June — the agent-native React framework. Contract layer (pure, host-free).",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://june.build",
+  "exports": {
+    ".": "./src/index.ts",
+    "./route": "./src/route.ts",
+    "./config": "./src/config.ts",
+    "./resources": "./src/resources.ts",
+    "./context": "./src/context.ts",
+    "./document": "./src/document.tsx",
+    "./islands": "./src/islands.tsx",
+    "./islands-client": "./src/islands-client.ts",
+    "./agent": "./src/agent.ts",
+    "./mcp": "./src/mcp.ts",
+    "./discovery": "./src/discovery.ts",
+    "./cache": "./src/cache.ts",
+    "./instrumentation": "./src/instrumentation.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "react": "^19.2.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/junebuild/june"
+  }
+}

package/src/agent.ts

@@ -0,0 +1,145 @@
+// agent.ts — the unified action registry + the agent-facing surface.
+//
+// One `defineAction()` entry is the single source of truth: it is the UI server
+// action, the `.agent` manifest tool, AND the MCP tool — all invoked by the
+// same id against this one registry. The RSC server-action path registers into
+// THIS registry too, so a server action and an agent/MCP tool are no longer
+// "the same thing described twice."
+//
+//   1. defineAction(): id + description + input schema + run.
+//   2. manifest.resource(name, data).actions([...]): the capability manifest a
+//      route returns to an agent client.
+//   3. invokeAction(id, input): the JSON dispatch path (agent / MCP). RSC's
+//      Flight dispatch resolves the same registry.
+
+import { currentTrace } from "./instrumentation";
+import type { ActionContext } from "./context";
+
+export type JsonSchema = {
+  type: "object";
+  properties: Record<string, { type: string; description?: string }>;
+  required?: string[];
+};
+
+export type ActionDefinition<I = unknown, O = unknown> = {
+  id: string;
+  description: string;
+  input: JsonSchema;
+  // run() receives the request-scoped context (principal + resources) as its
+  // second arg, so the SAME authorization runs on the UI and /mcp paths. An
+  // action that ignores ctx (one-param run) is still assignable here.
+  run: (input: I, ctx: ActionContext) => O | Promise<O>;
+};
+
+// `ActionDefinition` is invariant in its input type (the `run` param), so a
+// concretely-typed action is not assignable to `ActionDefinition<unknown>`.
+// Collections of heterogeneous actions use this loose alias.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyAction = ActionDefinition<any, any>;
+
+// The single, unified action registry — keyed on globalThis so any dispatch
+// path (agent POST, MCP tools/call, RSC Flight) resolves an action by id even
+// when the resolver loads this module twice (workspace symlinks can give the
+// app and the framework different @junejs/core paths; a module-level Map would
+// then split registrations across two instances).
+const REGISTRY_KEY = Symbol.for("june.actionRegistry");
+export const ACTION_REGISTRY: Map<string, AnyAction> = ((
+  globalThis as Record<symbol, Map<string, AnyAction> | undefined>
+)[REGISTRY_KEY] ??= new Map());
+
+// The RSC runtime (which owns the `react-server` condition) injects how to mark
+// a run() as a React server reference, so the SAME action is passable as a UI
+// prop without agent.ts importing react-server. No-op outside the RSC runtime.
+type ServerReferenceRegistrar = (
+  fn: (...args: unknown[]) => unknown,
+  id: string,
+) => unknown;
+let serverReferenceRegistrar: ServerReferenceRegistrar | null = null;
+export function setServerReferenceRegistrar(fn: ServerReferenceRegistrar) {
+  serverReferenceRegistrar = fn;
+}
+
+export function defineAction<I, O>(
+  def: ActionDefinition<I, O>,
+): ActionDefinition<I, O> {
+  ACTION_REGISTRY.set(def.id, def);
+  serverReferenceRegistrar?.(def.run as (...args: unknown[]) => unknown, def.id);
+  return def;
+}
+
+// JSON dispatch path (agent / MCP): invoke an action by id with a single input
+// and the request-scoped context (principal + resources). ctx defaults to {} so
+// callers that don't have one (tests, anonymous dispatch) still work.
+export async function invokeAction(
+  id: string,
+  input: unknown,
+  ctx: ActionContext = {},
+): Promise<unknown> {
+  const action = ACTION_REGISTRY.get(id);
+  if (!action) throw new Error(`Unknown action: ${id}`);
+  const result = await action.run(input, ctx);
+
+  // Cache coherence is a property of the ACTION, not of one dispatch path:
+  // every table this action wrote invalidates its `table:<name>` tag (plus the
+  // coarse `flight` tag), no matter how it was invoked — UI POST, /mcp
+  // tools/call, or Flight. (Idempotent if a caller also invalidates.)
+  const writes = currentTrace()?.writes;
+  if (writes && writes.size > 0) {
+    const { invalidate } = await import("./cache");
+    for (const table of writes) await invalidate(`table:${table}`);
+    await invalidate("flight");
+  }
+
+  return result;
+}
+
+type ActionManifestEntry = {
+  id: string;
+  description: string;
+  input: JsonSchema;
+  // How an agent invokes it. Mirrors the same dispatch the UI uses.
+  invoke: { method: "POST"; header: "x-june-action"; action: string };
+};
+
+export type ResourceManifestJson = {
+  resource: string;
+  data: unknown;
+  actions: ActionManifestEntry[];
+};
+
+export class ResourceManifest<T = unknown> {
+  private declared: AnyAction[] = [];
+
+  constructor(
+    private readonly name: string,
+    private readonly data: T,
+  ) {}
+
+  actions(actions: AnyAction[]) {
+    this.declared = actions;
+    return this;
+  }
+
+  toManifest(): ResourceManifestJson {
+    return {
+      resource: this.name,
+      data: this.data,
+      actions: this.declared.map((action) => ({
+        id: action.id,
+        description: action.description,
+        input: action.input,
+        invoke: { method: "POST", header: "x-june-action", action: action.id },
+      })),
+    };
+  }
+}
+
+export function isResourceManifest(value: unknown): value is ResourceManifest {
+  return value instanceof ResourceManifest;
+}
+
+export const manifest = {
+  resource<T>(name: string, data: T) {
+    return new ResourceManifest<T>(name, data);
+  },
+};

package/src/cache.ts

@@ -0,0 +1,245 @@
+// Cache primitives — first-class, not an afterthought (benchmarks show cache is
+// the difference between a render-bound ~5k rps and the native HTTP ceiling).
+//
+//   cache(fn, { key, ttl, tags })  memoize an async result
+//   invalidate(tag)                drop every entry carrying a tag
+//
+// Same adapter shape as the data layer: a CacheStore seam with a built-in
+// in-memory store (full tag support) and pluggable backends (redis, KV) behind
+// the same interface. The framework's route response cache uses this too.
+//
+// PURITY: the in-memory store and all of cache()/invalidate() are host-free.
+// The only host touch is the redis() factory's connect(), which dynamic-imports
+// "bun" through a NON-LITERAL specifier so no bundler resolves it statically —
+// the import only runs if a host opts into the redis store.
+
+import { currentTrace, recordTiming } from "./instrumentation";
+
+export type CacheEntry = {
+  value: unknown;
+  expiresAt: number | null; // fresh until this epoch ms (null = always fresh)
+  staleUntil: number | null; // servable-stale until this epoch ms (null = never dies)
+  tags: string[];
+};
+
+export interface CacheStore {
+  get(key: string): Promise<CacheEntry | null>;
+  set(key: string, entry: CacheEntry): Promise<void>;
+  delete(key: string): Promise<void>;
+  invalidateTag(tag: string): Promise<void>;
+}
+
+export interface CacheStoreFactory {
+  readonly kind: string;
+  connect(): Promise<CacheStore>;
+}
+
+// Built-in in-memory store with a tag -> keys index for O(tag) invalidation.
+class MemoryStore implements CacheStore {
+  private readonly entries = new Map<string, CacheEntry>();
+  private readonly tagIndex = new Map<string, Set<string>>();
+
+  async get(key: string): Promise<CacheEntry | null> {
+    const entry = this.entries.get(key);
+    if (!entry) return null;
+    // Alive (fresh or servable-stale) until staleUntil; cache() decides which.
+    if (entry.staleUntil !== null && entry.staleUntil < Date.now()) {
+      await this.delete(key);
+      return null;
+    }
+    return entry;
+  }
+
+  async set(key: string, entry: CacheEntry): Promise<void> {
+    await this.delete(key); // clear any stale tag links
+    this.entries.set(key, entry);
+    for (const tag of entry.tags) {
+      let keys = this.tagIndex.get(tag);
+      if (!keys) this.tagIndex.set(tag, (keys = new Set()));
+      keys.add(key);
+    }
+  }
+
+  async delete(key: string): Promise<void> {
+    const entry = this.entries.get(key);
+    this.entries.delete(key);
+    if (entry) {
+      for (const tag of entry.tags) this.tagIndex.get(tag)?.delete(key);
+    }
+  }
+
+  async invalidateTag(tag: string): Promise<void> {
+    const keys = this.tagIndex.get(tag);
+    if (!keys) return;
+    for (const key of [...keys]) await this.delete(key);
+    this.tagIndex.delete(tag);
+  }
+}
+
+let store: CacheStore | null = null;
+
+export function registerCache(s: CacheStore) {
+  store = s;
+}
+
+export async function configureCache(factory: CacheStoreFactory) {
+  store = await factory.connect();
+}
+
+function active(): CacheStore {
+  // Zero-config fallback: the built-in in-memory store.
+  return store ?? (store = new MemoryStore());
+}
+
+export type CacheOptions = {
+  key: string;
+  ttl?: number; // fresh window, seconds
+  swr?: number; // extra stale-while-revalidate window, seconds (needs ttl)
+  tags?: string[];
+};
+
+function entryOf(opts: CacheOptions, value: unknown, tags: string[]): CacheEntry {
+  const now = Date.now();
+  const expiresAt = opts.ttl ? now + opts.ttl * 1000 : null;
+  const staleUntil =
+    expiresAt !== null && opts.swr ? expiresAt + opts.swr * 1000 : expiresAt;
+  return { value, expiresAt, staleUntil, tags };
+}
+
+// Coalesce background refreshes so a burst of stale hits triggers one recompute.
+const revalidating = new Set<string>();
+
+async function revalidate<T>(
+  s: CacheStore,
+  fn: () => T | Promise<T>,
+  opts: CacheOptions,
+  tags: string[], // reuse the stale entry's tags (no request trace in the background)
+) {
+  if (revalidating.has(opts.key)) return;
+  revalidating.add(opts.key);
+  try {
+    await s.set(opts.key, entryOf(opts, await fn(), tags));
+  } catch {
+    /* keep serving the stale value */
+  } finally {
+    revalidating.delete(opts.key);
+  }
+}
+
+// Memoize an async result. Fresh hits return immediately; within the SWR window
+// a stale value is returned immediately while a refresh runs in the background.
+export async function cache<T>(
+  fn: () => T | Promise<T>,
+  opts: CacheOptions,
+): Promise<T> {
+  const s = active();
+  const entry = await s.get(opts.key);
+
+  if (entry) {
+    const fresh = entry.expiresAt === null || entry.expiresAt > Date.now();
+    if (fresh) {
+      recordTiming("cache", "HIT", 0, opts.key);
+      return entry.value as T;
+    }
+    // Stale but within the SWR window: serve stale now, refresh in background.
+    recordTiming("cache", "STALE", 0, opts.key);
+    void revalidate(s, fn, opts, entry.tags);
+    return entry.value as T;
+  }
+
+  // Miss — auto-tag by the tables fn() reads (diff the trace before/after), so
+  // invalidation works without hand-declared tags. Explicit tags merge in.
+  const before = new Set(currentTrace()?.reads ?? []);
+  const value = await fn();
+  const autoTags = [...(currentTrace()?.reads ?? [])]
+    .filter((t) => !before.has(t))
+    .map((t) => `table:${t}`);
+
+  await s.set(opts.key, entryOf(opts, value, [...(opts.tags ?? []), ...autoTags]));
+  recordTiming(
+    "cache",
+    "MISS",
+    0,
+    `${opts.key}${autoTags.length ? ` [${autoTags.join(",")}]` : ""}`,
+  );
+  return value;
+}
+
+// Drop every cache entry carrying this tag. Call from mutations.
+export async function invalidate(tag: string): Promise<void> {
+  await active().invalidateTag(tag);
+}
+
+// Config form: `cache: memory()` (default) or `cache: redis({ url })`.
+export function memory(): CacheStoreFactory {
+  return {
+    kind: "memory",
+    async connect() {
+      return new MemoryStore();
+    },
+  };
+}
+
+// Redis-backed store (Bun's native client). Tags use Redis sets for O(tag)
+// invalidation. Needs a Redis server — same seam as the in-memory store.
+interface RedisLike {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string): Promise<unknown>;
+  del(key: string): Promise<unknown>;
+  expire(key: string, seconds: number): Promise<unknown>;
+  sadd(key: string, member: string): Promise<unknown>;
+  srem(key: string, member: string): Promise<unknown>;
+  smembers(key: string): Promise<string[]>;
+}
+
+class RedisStore implements CacheStore {
+  constructor(private readonly client: RedisLike) {}
+
+  async get(key: string): Promise<CacheEntry | null> {
+    const raw = await this.client.get(key);
+    if (!raw) return null;
+    const entry = JSON.parse(raw) as CacheEntry;
+    if (entry.staleUntil !== null && entry.staleUntil < Date.now()) {
+      await this.delete(key);
+      return null;
+    }
+    return entry;
+  }
+
+  async set(key: string, entry: CacheEntry): Promise<void> {
+    await this.client.set(key, JSON.stringify(entry));
+    if (entry.staleUntil) {
+      await this.client.expire(key, Math.ceil((entry.staleUntil - Date.now()) / 1000));
+    }
+    for (const tag of entry.tags) await this.client.sadd(`tag:${tag}`, key);
+  }
+
+  async delete(key: string): Promise<void> {
+    const raw = await this.client.get(key);
+    await this.client.del(key);
+    if (raw) {
+      const entry = JSON.parse(raw) as CacheEntry;
+      for (const tag of entry.tags) await this.client.srem(`tag:${tag}`, key);
+    }
+  }
+
+  async invalidateTag(tag: string): Promise<void> {
+    for (const key of await this.client.smembers(`tag:${tag}`)) await this.delete(key);
+    await this.client.del(`tag:${tag}`);
+  }
+}
+
+export function redis(opts: { url: string }): CacheStoreFactory {
+  return {
+    kind: "redis",
+    async connect() {
+      // Non-literal specifier: bundlers (wrangler/esbuild for Workers) must not
+      // try to resolve "bun" — it exists only at Bun runtime.
+      const bunSpecifier = "bun";
+      const mod = (await import(bunSpecifier)) as unknown as {
+        RedisClient: new (url: string) => RedisLike;
+      };
+      return new RedisStore(new mod.RedisClient(opts.url));
+    },
+  };
+}

package/src/config.ts

@@ -0,0 +1,111 @@
+// june.config.ts support — the resource manifest / feature config.
+//
+// The agent surface (discovery + MCP) is ON by default: it exposes the same
+// actions and the same authorization the UI already exposes, so it does not
+// widen the attack surface. Gate sensitive actions with permissions, not by
+// hiding the endpoint. Turn any of it off here when you must.
+//
+// PURITY: this module is the config SCHEMA and its pure resolvers only. The
+// `loadJuneConfig(appDir)` reader (node:fs / node:path / dynamic import of the
+// user's june.config.ts) is a HOST concern and lives in the Phase-2 host layer
+// — keeping the contract layer free of `node:*` (zero node:*/Bun.* in this layer).
+
+import type { CacheStoreFactory } from "./cache";
+import type { ResourceConfig } from "./resources";
+
+export type AgentConfig = {
+  enabled: boolean; // master switch
+  discovery: boolean; // Link header, llms.txt, sitemap, api-catalog, mcp server-card
+  mcp: boolean; // the /mcp execution endpoint
+  webmcp: boolean; // inject WebMCP tool registrations into the view
+};
+
+export type SpeculationConfig = {
+  // hover-intent prerender: "moderate" (hover) | "conservative" (mousedown,
+  // for heavy pages) | false. Default "moderate" — light MPA pages get 0ms
+  // navigations for free.
+  prerender?: "moderate" | "conservative" | false;
+  prefetch?: "moderate" | "conservative" | false;
+  // App-specific exclusions, ADDED to the built-in ones (agent surfaces:
+  // *.md *.json *.agent *.txt *.xml /mcp — those are always excluded).
+  exclude?: string[];
+  // "inline" (default): rules in a <script type=speculationrules>.
+  // "header": rules served at /__june/speculation-rules and referenced by a
+  // `Speculation-Rules` response header — smaller HTML, CDN-injectable.
+  delivery?: "inline" | "header";
+};
+
+export type JuneConfig = {
+  agent?: Partial<AgentConfig>;
+  cache?: CacheStoreFactory; // memory() (default) | redis({ url }) | custom
+  // Data resources (db / blob / kv), declared = enabled. Generic names, not
+  // Cloudflare-branded; each has a zero-config local default and deploy
+  // adapters. Omit one and it never exists. See docs/data-layer-boundary.md.
+  resources?: ResourceConfig;
+  speculation?: SpeculationConfig | false; // false = no speculation rules at all
+  // Cross-document View Transitions (@view-transition CSS): MPA navigations
+  // animate (default cross-fade) with ZERO JS; browsers without support (or
+  // users with prefers-reduced-motion) get instant navigation — the floor.
+  viewTransitions?: boolean; // default true
+  // Early Hints (IETF RFC 8297): Link rel=preload values for critical assets
+  // (fonts/CSS), e.g. ["</fonts/inter.woff2>; rel=preload; as=font; crossorigin"].
+  // Floor: sent as a Link header on HTML responses (Cloudflare upgrades it to
+  // a real 103 at the edge). On the Node host, June emits the 103 itself.
+  earlyHints?: string[];
+  // Site-wide metadata defaults: per-route metadata merges over these.
+  // titleTemplate: "%s" is replaced by the route's title ("%s — Acme").
+  site?: { name?: string; titleTemplate?: string; description?: string };
+  // `june build` options. external: packages left UNBUNDLED in dist/worker.js
+  // (wrangler resolves them at deploy with its own rules — needed for packages
+  // that import .wasm, e.g. workers-og).
+  build?: { external?: string[] };
+  // `june deploy` options. The deploy VERB is fixed; the target is an adapter
+  // (same seam philosophy as JuneHost) — "workers" today, "node"/"june-cloud"
+  // later. name defaults to package.json name.
+  deploy?: { target?: "workers"; name?: string };
+};
+
+const DEFAULT_AGENT: AgentConfig = {
+  enabled: true,
+  discovery: true,
+  mcp: true,
+  webmcp: true,
+};
+
+export function defineJune(config: JuneConfig): JuneConfig {
+  return config;
+}
+
+export function resolveAgent(partial?: Partial<AgentConfig>): AgentConfig {
+  const merged = { ...DEFAULT_AGENT, ...(partial ?? {}) };
+  // The master switch turns the whole agent surface off.
+  if (!merged.enabled) {
+    return { enabled: false, discovery: false, mcp: false, webmcp: false };
+  }
+  return merged;
+}
+
+// --- speculation (hover prerender/prefetch) -----------------------------------
+
+// Agent surfaces are ALWAYS excluded from human-intent speculation — humans
+// hover, agents don't; a footer link to llms.txt must not prerender.
+const BUILTIN_EXCLUDES = ["/*.md", "/*.json", "/*.agent", "/*.txt", "/*.xml", "/mcp"];
+
+export function resolveSpeculationRules(config?: SpeculationConfig | false): string | null {
+  if (config === false) return null;
+  const prerender = config?.prerender ?? "moderate";
+  const prefetch = config?.prefetch ?? "moderate";
+  if (!prerender && !prefetch) return null;
+  const where = {
+    and: [
+      { href_matches: "/*" },
+      ...[...BUILTIN_EXCLUDES, ...(config?.exclude ?? [])].map((p) => ({
+        not: { href_matches: p },
+      })),
+    ],
+  };
+  const rules: Record<string, unknown> = {};
+  if (prerender) rules.prerender = [{ where, eagerness: prerender }];
+  if (prefetch) rules.prefetch = [{ where, eagerness: prefetch }];
+  return JSON.stringify(rules);
+}

package/src/context.ts

@@ -0,0 +1,25 @@
+// Request-scoped context shared by routes and actions: the authenticated
+// principal + the data resources. PURE — the principal types are abstract; the
+// auth integration (@junejs/auth, Better Auth) refines them. @junejs/core never
+// imports an auth library; the host populates these off the request.
+// See docs/auth-integration.md.
+
+import type { JuneDb, JuneKv, JuneBlob } from "./resources";
+
+// The authenticated user. Abstract on purpose — Better Auth's user shape slots
+// in via declaration merging / the auth package's own typing.
+export type Principal = { id: string; [key: string]: unknown };
+export type Session = { id: string; [key: string]: unknown };
+
+// What a defineAction's run() receives as its SECOND argument: the same
+// request-scoped principal + resources a route's load() sees. This is what lets
+// the UI dispatch and the /mcp path share ONE authorization model — an agent
+// calling a tool runs through the exact same `ctx.user` check as the UI.
+export type ActionContext = {
+  request?: Request;
+  user?: Principal;
+  session?: Session;
+  db?: JuneDb;
+  kv?: JuneKv;
+  blob?: JuneBlob;
+};