@janux/server 0.1.0

package/README.md

@@ -0,0 +1,3 @@
+# @janux/server
+
+Fullstack server for [Janux](https://github.com/aralroca/Janux): `api()` server functions that are simultaneously validated HTTP endpoints, typed client stubs and agent tools; file-system router; HTML shell with the 0-KB-JS static-page guarantee; `/_janux/*` endpoints (manifest, agent, proposals).

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@janux/server",
+  "version": "0.1.0",
+  "description": "Janux fullstack server: SSR, api() RPC endpoints that double as agent tools, manifest service and MCP surface.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aralroca/Janux.git"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Aral Roca Gomez",
+    "email": "contact@aralroca.com"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "janux": "0.1.0"
+  },
+  "homepage": "https://github.com/aralroca/Janux#readme",
+  "bugs": "https://github.com/aralroca/Janux/issues",
+  "keywords": [
+    "janux",
+    "agentic-ui",
+    "mcp",
+    "webmcp",
+    "ai-agents",
+    "fullstack",
+    "framework",
+    "bun",
+    "vite",
+    "resumability",
+    "copilot"
+  ],
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/api.ts

@@ -0,0 +1,103 @@
+import { JxType, validate, toJsonSchema, JanuxIntentError } from 'janux';
+import type { Ctx, Guard, GuardValue, Origin } from 'janux';
+
+export interface ApiDef {
+  description?: string;
+  input?: JxType;
+  output?: JxType;
+  guard?: Guard;
+  run: (bag: { input: any; ctx: Ctx }) => unknown;
+}
+
+export interface ApiTool extends ApiDef {
+  name: string;
+}
+
+const API_MARK = Symbol.for('janux.api');
+
+export type CallableApi = ((input?: unknown) => Promise<unknown>) & ApiDef;
+
+/**
+ * Defines a server function that is simultaneously an HTTP endpoint, a typed
+ * client stub and an agent tool. The returned value is directly callable on
+ * the server (SSR sources, other apis); client bundles swap it for a fetch stub.
+ */
+export function api(def: ApiDef): CallableApi {
+  if (typeof def.run !== 'function') throw new Error('Janux: api() requires run()');
+  const callable = (input?: unknown) =>
+    invokeApi({ ...def, name: 'inline' }, input, {}, 'human');
+
+  return Object.assign(callable, def, { [API_MARK]: true }) as CallableApi;
+}
+
+export function isApi(value: unknown): value is ApiDef {
+  return value !== null && value !== undefined && API_MARK in Object(value);
+}
+
+/** Collects api() exports from modules into namespaced tools: `{shop: mod}` → `api.shop.searchOrders`. */
+export function collectApis(modules: Record<string, Record<string, unknown>>): ApiTool[] {
+  return Object.entries(modules).flatMap(([moduleName, mod]) =>
+    Object.entries(mod)
+      .filter(([, value]) => isApi(value))
+      .map(([exportName, value]) => {
+        if (`${moduleName}.${exportName}`.includes('__')) {
+          throw new Error(
+            `Janux: api name "${moduleName}.${exportName}" may not contain "__" (reserved for tool wire names)`,
+          );
+        }
+
+        return { ...(value as ApiDef), name: `${moduleName}.${exportName}` };
+      }),
+  );
+}
+
+export function resolveApiGuard(tool: ApiTool, ctx: Ctx): GuardValue {
+  const guard = tool.guard ?? 'auto';
+
+  return typeof guard === 'function' ? guard({ ctx }) : guard;
+}
+
+function parseApiInput(tool: ApiTool, input: unknown): unknown {
+  if (!tool.input) return undefined;
+  const result = validate(tool.input, input ?? {});
+
+  if (!result.ok) {
+    const detail = result.errors.map((e) => `${e.path}: ${e.message}`).join('; ');
+
+    throw new JanuxIntentError('invalid_input', `Invalid input for "${tool.name}" — ${detail}`);
+  }
+
+  return result.value;
+}
+
+/** Single invocation pipeline for api() tools: guard → validate → run → validate output. */
+export async function invokeApi(tool: ApiTool, input: unknown, ctx: Ctx, origin: Origin): Promise<unknown> {
+  const guard = resolveApiGuard(tool, ctx);
+
+  if (origin === 'agent' && guard === 'forbidden') {
+    throw new JanuxIntentError('forbidden', `Tool "${tool.name}" is not available`);
+  }
+  const parsed = parseApiInput(tool, input);
+  const result = await tool.run({ input: parsed, ctx });
+
+  if (tool.output) {
+    const check = validate(tool.output, result);
+
+    if (!check.ok) throw new Error(`Janux: api "${tool.name}" returned an invalid output`);
+
+    return check.value;
+  }
+
+  return result;
+}
+
+export function apiManifestTools(tools: ApiTool[], ctx: Ctx) {
+  return tools
+    .filter((tool) => resolveApiGuard(tool, ctx) !== 'forbidden')
+    .map((tool) => ({
+      name: `api.${tool.name}`,
+      description: tool.description,
+      guard: resolveApiGuard(tool, ctx),
+      input: tool.input ? toJsonSchema(tool.input) : undefined,
+    }));
+}

package/src/html-shell.ts

@@ -0,0 +1,67 @@
+export interface ShellOptions {
+  html: string;
+  title?: string;
+  snapshots: { uri: string; state: Record<string, unknown>; sources?: Record<string, unknown> }[];
+  islandNames: string[];
+  islandModules?: Record<string, string>;
+  runtimeUrl?: string;
+  manifestUrl?: string;
+  stylesheets?: string[];
+}
+
+function safeJson(value: unknown): string {
+  return JSON.stringify(value).replace(/</g, '\\u003c');
+}
+
+function safeAttr(value: string): string {
+  return value.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
+}
+
+function stateScripts(snapshots: ShellOptions['snapshots']): string {
+  return snapshots
+    .map((snapshot) => {
+      const payload = safeJson({ state: snapshot.state, sources: snapshot.sources ?? {} });
+
+      return `<script type="application/janux+state" data-uri="${safeAttr(snapshot.uri)}">${payload}</script>`;
+    })
+    .join('\n');
+}
+
+function runtimeScripts(options: ShellOptions): string {
+  if (options.islandNames.length === 0) return '';
+  const modules = Object.fromEntries(
+    options.islandNames.map((name) => [name, options.islandModules?.[name] ?? '']),
+  );
+
+  return [
+    `<script>window.__JANUX_ISLANDS__=${safeJson(modules)}</script>`,
+    options.runtimeUrl ? `<script type="module" src="${options.runtimeUrl}"></script>` : '',
+  ].join('\n');
+}
+
+/**
+ * Full HTML document. Static pages (no islands) ship ZERO JavaScript:
+ * no runtime script, no import map, no state — just HTML.
+ */
+export function htmlDocument(options: ShellOptions): string {
+  const manifestLink = options.manifestUrl
+    ? `<link rel="janux-manifest" href="${options.manifestUrl}">`
+    : '';
+  const styleLinks = (options.stylesheets ?? [])
+    .map((href) => `<link rel="stylesheet" href="${safeAttr(href)}">`)
+    .join('');
+
+  return [
+    '<!doctype html>',
+    '<html>',
+    `<head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${options.title ?? 'Janux app'}</title>${manifestLink}${styleLinks}</head>`,
+    '<body>',
+    options.html,
+    options.islandNames.length > 0 ? stateScripts(options.snapshots) : '',
+    runtimeScripts(options),
+    '</body>',
+    '</html>',
+  ]
+    .filter(Boolean)
+    .join('\n');
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export { api, collectApis, invokeApi, apiManifestTools, isApi, type ApiDef, type ApiTool } from './api';
+export { createJanuxServer, type ServerOptions, type AgentMount, type AgentDeps } from './server';
+export { createFsRouter, type RouteMatch } from './router';
+export { htmlDocument, type ShellOptions } from './html-shell';

package/src/router.ts

@@ -0,0 +1,81 @@
+import { readdirSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+export interface Route {
+  pattern: string;
+  segments: string[];
+  filePath: string;
+}
+
+export interface RouteMatch {
+  filePath: string;
+  pattern: string;
+  params: Record<string, string>;
+}
+
+const PAGE_EXTENSIONS = /\.(tsx|jsx|ts|js)$/;
+
+function walk(dir: string): string[] {
+  return readdirSync(dir).flatMap((entry) => {
+    const full = join(dir, entry);
+
+    if (statSync(full).isDirectory()) return walk(full);
+
+    return PAGE_EXTENSIONS.test(entry) && !entry.startsWith('_') ? [full] : [];
+  });
+}
+
+function patternFor(dir: string, filePath: string): string {
+  const raw = relative(dir, filePath).replace(PAGE_EXTENSIONS, '');
+  const withoutIndex = raw === 'index' ? '' : raw.replace(/\/index$/, '');
+
+  return `/${withoutIndex}`.replace(/\/+/g, '/');
+}
+
+function matchSegments(routeSegments: string[], pathSegments: string[]) {
+  if (routeSegments.length !== pathSegments.length) return undefined;
+  const params: Record<string, string> = {};
+  const matched = routeSegments.every((segment, index) => {
+    const value = pathSegments[index]!;
+    const dynamic = /^\[(.+)\]$/.exec(segment);
+
+    if (dynamic) {
+      params[dynamic[1]!] = decodeURIComponent(value);
+
+      return true;
+    }
+
+    return segment === value;
+  });
+
+  return matched ? params : undefined;
+}
+
+/** File-system router: `routes/index.tsx` → `/`, `routes/orders/[id].tsx` → `/orders/:id`. */
+export function createFsRouter(dir: string) {
+  const routes: Route[] = walk(dir)
+    .map((filePath) => {
+      const pattern = patternFor(dir, filePath);
+
+      return { pattern, filePath, segments: pattern.split('/').filter(Boolean) };
+    })
+    .sort((a, b) => a.pattern.localeCompare(b.pattern));
+
+  return {
+    routes,
+    match(pathname: string): RouteMatch | undefined {
+      const pathSegments = pathname.split('/').filter(Boolean);
+      const staticFirst = [...routes].sort(
+        (a, b) => Number(a.pattern.includes('[')) - Number(b.pattern.includes('[')),
+      );
+
+      return staticFirst
+        .map((route) => {
+          const params = matchSegments(route.segments, pathSegments);
+
+          return params ? { filePath: route.filePath, pattern: route.pattern, params } : undefined;
+        })
+        .find(Boolean);
+    },
+  };
+}

package/src/server.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, it } from 'bun:test';
+import { component, intent, jsx, schema, str, int, list } from 'janux';
+import { api } from './api';
+import { createJanuxServer } from './server';
+
+const orders = [
+  { id: 'o1', status: 'pending' },
+  { id: 'o2', status: 'paid' },
+];
+
+const shopApis = {
+  searchOrders: api({
+    description: 'Search orders by status',
+    input: schema({ status: str() }),
+    run: ({ input }) => orders.filter((order) => order.status === input.status),
+  }),
+  refundOrder: api({
+    description: 'Refund an order. Irreversible.',
+    input: schema({ orderId: str() }),
+    guard: 'confirm',
+    run: ({ input }) => ({ refunded: input.orderId }),
+  }),
+  internal: api({ guard: 'forbidden', run: () => 'secret' }),
+};
+
+const cart = component({
+  name: 'cart',
+  state: schema({ items: list({ id: str(), qty: int() }) }),
+  intents: { add: intent({ input: schema({ id: str() }), run: ({ state, input }) => state.items.push({ id: input.id, qty: 1 }) }) },
+  view: ({ state }: any) => jsx('p', { children: `${state.items.length} items` }),
+});
+
+function Landing() {
+  return jsx('main', { children: jsx('h1', { children: 'Welcome' }) });
+}
+
+const server = createJanuxServer({
+  routes: {
+    '/': () => jsx(Landing as any, {}),
+    '/shop': () => jsx('div', { children: jsx(cart as any, {}) }),
+  },
+  apis: { shop: shopApis },
+  runtimeUrl: '/_janux/client.js',
+  islandModules: { cart: '/islands/cart.js' },
+});
+
+const get = (path: string) => server.fetch(new Request(`http://test${path}`));
+const post = (path: string, body: unknown, headers: Record<string, string> = {}) =>
+  server.fetch(
+    new Request(`http://test${path}`, {
+      method: 'POST',
+      body: JSON.stringify(body),
+      headers: { 'content-type': 'application/json', ...headers },
+    }),
+  );
+
+describe('pages', () => {
+  it('serves static pages with ZERO JavaScript', async () => {
+    const html = await (await get('/')).text();
+
+    expect(html).toContain('<h1>Welcome</h1>');
+    expect(html).not.toContain('<script');
+    expect(html).toContain('rel="janux-manifest"');
+  });
+
+  it('serves island pages with snapshots, island map and runtime', async () => {
+    const html = await (await get('/shop')).text();
+
+    expect(html).toContain('<janux-island data-jx="cart#default">');
+    expect(html).toContain('data-uri="ui://cart#default"');
+    expect(html).toContain('window.__JANUX_ISLANDS__={"cart":"/islands/cart.js"}');
+    expect(html).toContain('src="/_janux/client.js"');
+  });
+
+  it('404s unknown routes', async () => {
+    expect((await get('/nope')).status).toBe(404);
+  });
+});
+
+describe('api endpoints', () => {
+  it('runs api tools with validated input', async () => {
+    const res = await post('/_janux/api/shop.searchOrders', { status: 'paid' });
+    const body: any = await res.json();
+
+    expect(body).toEqual({ ok: true, result: [{ id: 'o2', status: 'paid' }] });
+  });
+
+  it('rejects invalid input with 400', async () => {
+    const res = await post('/_janux/api/shop.searchOrders', {});
+
+    expect(res.status).toBe(400);
+    expect(((await res.json()) as any).error).toContain('status: required');
+  });
+
+  it('human origin runs confirm tools directly', async () => {
+    const body: any = await (await post('/_janux/api/shop.refundOrder', { orderId: 'o1' })).json();
+
+    expect(body.result).toEqual({ refunded: 'o1' });
+  });
+
+  it('agent origin gets a proposal for confirm tools; approve executes it', async () => {
+    const res = await post('/_janux/api/shop.refundOrder', { orderId: 'o1' }, { 'x-janux-origin': 'agent' });
+    const proposal: any = ((await res.json()) as any).result;
+
+    expect(proposal.status).toBe('proposal');
+    const approved: any = await (await post('/_janux/approve', { id: proposal.id })).json();
+
+    expect(approved.result).toEqual({ refunded: 'o1' });
+    expect((await post('/_janux/approve', { id: proposal.id })).status).toBe(404);
+  });
+
+  it('agent origin cannot call forbidden tools', async () => {
+    const res = await post('/_janux/api/shop.internal', {}, { 'x-janux-origin': 'agent' });
+
+    expect(res.status).toBe(403);
+  });
+});
+
+describe('manifest endpoint', () => {
+  it('merges mounted islands and api tools per route', async () => {
+    const manifest: any = await (await get('/_janux/manifest?path=/shop')).json();
+    const toolNames = manifest.tools.map((tool: any) => tool.name);
+
+    expect(manifest.resources.map((r: any) => r.uri)).toContain('ui://cart');
+    expect(toolNames).toContain('cart.add');
+    expect(toolNames).toContain('api.shop.searchOrders');
+    expect(toolNames).not.toContain('api.shop.internal');
+  });
+
+  it('static routes expose only api tools', async () => {
+    const manifest: any = await (await get('/_janux/manifest?path=/')).json();
+
+    expect(manifest.resources).toEqual([]);
+    expect(manifest.tools.every((tool: any) => tool.name.startsWith('api.'))).toBe(true);
+  });
+});

package/src/server.ts

@@ -0,0 +1,207 @@
+import { buildManifest, renderToString, validate, type ComponentDef, type Ctx } from 'janux';
+import { apiManifestTools, collectApis, invokeApi, resolveApiGuard, type ApiTool } from './api';
+import { createFsRouter } from './router';
+import { htmlDocument } from './html-shell';
+
+export interface AgentMount {
+  handle(req: Request, deps: AgentDeps): Promise<Response>;
+}
+
+export interface AgentDeps {
+  tools: ApiTool[];
+  invoke: (tool: string, input: unknown) => Promise<unknown>;
+  manifestFor: (path: string) => Promise<unknown>;
+}
+
+export interface ServerOptions {
+  routesDir?: string;
+  loadRoute?: (filePath: string) => Promise<Record<string, unknown>>;
+  routes?: Record<string, (props: { ctx: Ctx; params: Record<string, string> }) => unknown>;
+  apis?: Record<string, Record<string, unknown>>;
+  storeDefs?: Record<string, ComponentDef>;
+  agent?: AgentMount;
+  ctxFor?: (req: Request) => Ctx | Promise<Ctx>;
+  runtimeUrl?: string;
+  islandModules?: Record<string, string>;
+  title?: string;
+  stylesheets?: string[];
+}
+
+interface PendingApiProposal {
+  id: string;
+  tool: string;
+  input: unknown;
+  execute: () => Promise<unknown>;
+}
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+const MAX_PENDING_PROPOSALS = 100;
+
+function evictOldestProposal(proposals: Map<string, PendingApiProposal>): void {
+  if (proposals.size < MAX_PENDING_PROPOSALS) return;
+  const oldest = proposals.keys().next().value;
+
+  if (oldest) proposals.delete(oldest);
+}
+
+function assertValidInput(tool: { name: string; input?: any }, input: unknown): unknown {
+  const result = validate(tool.input, input ?? {});
+
+  if (!result.ok) {
+    const detail = result.errors.map((e: any) => `${e.path}: ${e.message}`).join('; ');
+
+    throw Object.assign(new Error(`Invalid input for "${tool.name}" — ${detail}`), {
+      code: 'invalid_input',
+    });
+  }
+
+  return result.value;
+}
+
+function errorStatus(error: unknown): number {
+  const code = (error as any)?.code;
+
+  return code === 'forbidden' ? 403 : code === 'invalid_input' ? 400 : 500;
+}
+
+let proposalSeq = 0;
+
+/** The Janux fullstack server: pages, api() endpoints, manifest, proposals and the agent mount. */
+export function createJanuxServer(options: ServerOptions = {}) {
+  const apiTools = collectApis(options.apis ?? {});
+  const router = options.routesDir ? createFsRouter(options.routesDir) : undefined;
+  const loadRoute = options.loadRoute ?? ((filePath: string) => import(/* @vite-ignore */ filePath));
+  const proposals = new Map<string, PendingApiProposal>();
+
+  const resolveCtx = async (req: Request): Promise<Ctx> => (await options.ctxFor?.(req)) ?? {};
+
+  const findRoute = (pathname: string) => {
+    if (options.routes?.[pathname]) {
+      return { render: options.routes[pathname]!, params: {} as Record<string, string> };
+    }
+    const match = router?.match(pathname);
+
+    return match ? { load: match.filePath, params: match.params } : undefined;
+  };
+
+  const renderPage = async (pathname: string, ctx: Ctx) => {
+    const route = findRoute(pathname);
+
+    if (!route) return undefined;
+    const render = 'render' in route ? route.render : ((await loadRoute(route.load)) as any).default;
+    const vnode = render({ ctx, params: route.params });
+
+    return renderToString(vnode, { ctx, storeDefs: options.storeDefs });
+  };
+
+  const manifestFor = async (pathname: string, ctx: Ctx): Promise<unknown> => {
+    const result = await renderPage(pathname, ctx);
+    const entries = result
+      ? [
+          ...result.registry.islands.map(({ def, key, instance }) => ({ def, key, instance })),
+          ...[...result.registry.stores.values()].map((instance) => ({ def: instance.def, instance })),
+        ]
+      : [];
+    const base = buildManifest(entries, ctx);
+
+    return { ...base, tools: [...base.tools, ...apiManifestTools(apiTools, ctx)] };
+  };
+
+  const invokeTool = async (name: string, input: unknown, ctx: Ctx): Promise<unknown> => {
+    const tool = apiTools.find((candidate) => `api.${candidate.name}` === name || candidate.name === name);
+
+    if (!tool) throw Object.assign(new Error(`Unknown api tool "${name}"`), { code: 'invalid_input' });
+
+    return invokeApi(tool, input, ctx, 'agent');
+  };
+
+  const handleApi = async (req: Request, name: string): Promise<Response> => {
+    const tool = apiTools.find((candidate) => candidate.name === name);
+
+    if (!tool) return json({ ok: false, error: `Unknown api "${name}"` }, 404);
+    const origin = req.headers.get('x-janux-origin') === 'agent' ? 'agent' : 'human';
+    const input = await req.json().catch(() => ({}));
+    const ctx = await resolveCtx(req);
+
+    try {
+      if (origin === 'agent' && resolveApiGuard(tool, ctx) === 'confirm') {
+        const parsed = tool.input ? assertValidInput(tool, input) : input;
+        const id = `prop_api_${(proposalSeq += 1)}`;
+
+        evictOldestProposal(proposals);
+        proposals.set(id, { id, tool: tool.name, input: parsed, execute: () => invokeApi(tool, parsed, ctx, 'human') });
+
+        return json({ ok: true, result: { status: 'proposal', id, tool: tool.name, input: parsed } });
+      }
+
+      return json({ ok: true, result: await invokeApi(tool, input, ctx, origin) });
+    } catch (error) {
+      return json({ ok: false, error: String(error) }, errorStatus(error));
+    }
+  };
+
+  const handleApprove = async (req: Request): Promise<Response> => {
+    const { id } = (await req.json().catch(() => ({}))) as { id?: string };
+    const proposal = id ? proposals.get(id) : undefined;
+
+    if (!proposal) return json({ ok: false, error: 'unknown proposal' }, 404);
+    proposals.delete(proposal.id);
+
+    return json({ ok: true, result: await proposal.execute() });
+  };
+
+  const handlePage = async (req: Request, pathname: string): Promise<Response> => {
+    const ctx = await resolveCtx(req);
+    const result = await renderPage(pathname, ctx);
+
+    if (!result) return new Response('Not found', { status: 404 });
+    const islandNames = [...new Set(result.registry.islands.map(({ def }) => def.name))];
+    const html = htmlDocument({
+      html: result.html,
+      title: options.title,
+      snapshots: result.snapshots,
+      islandNames,
+      islandModules: options.islandModules,
+      runtimeUrl: islandNames.length > 0 ? options.runtimeUrl : undefined,
+      manifestUrl: `/_janux/manifest?path=${encodeURIComponent(pathname)}`,
+      stylesheets: options.stylesheets,
+    });
+
+    return new Response(html, { headers: { 'content-type': 'text/html; charset=utf-8' } });
+  };
+
+  const fetch = async (req: Request): Promise<Response> => {
+    const url = new URL(req.url);
+    const { pathname } = url;
+
+    if (pathname.startsWith('/_janux/api/')) return handleApi(req, pathname.slice('/_janux/api/'.length));
+    if (pathname === '/_janux/approve') return handleApprove(req);
+    if (pathname === '/_janux/reject') {
+      const { id } = (await req.json().catch(() => ({}))) as { id?: string };
+
+      return json({ ok: id ? proposals.delete(id) : false });
+    }
+    if (pathname === '/_janux/manifest') {
+      return json(await manifestFor(url.searchParams.get('path') ?? '/', await resolveCtx(req)));
+    }
+    if (pathname === '/_janux/agent' && options.agent) {
+      const ctx = await resolveCtx(req);
+
+      return options.agent.handle(req, {
+        tools: apiTools,
+        invoke: (tool, input) => invokeTool(tool, input, ctx),
+        manifestFor: (path) => manifestFor(path, ctx),
+      });
+    }
+
+    return handlePage(req, pathname);
+  };
+
+  return { fetch, apiTools, manifestFor };
+}