@waniwani/kit 0.1.1 → 0.1.4

package/src/server.ts

@@ -11,9 +11,10 @@
  * hands them to `registerApp()`. Nothing else.
  */
 
+import cors from "cors";
+import express, { type ErrorRequestHandler, type RequestHandler } from "express";
 import { McpServer, type ViewName } from "skybridge/server";
-import { z } from "zod";
-import type { DocEntry, Shape, ToolHints, WidgetCsp } from "./index.js";
+import type { EndpointDefinition, HttpMethod, Shape, ToolHints, WidgetCsp } from "./index.js";
 
 /**
  * The manifest holds definitions with unrelated schemas side by side, so the
@@ -52,7 +53,8 @@ export type Manifest = {
 	tools: Array<{ name: string; def: AnyToolDefinition }>;
 	widgets: Array<{ name: string; def: AnyWidgetDefinition }>;
 	flows: CompiledFlow[];
-	docs: DocEntry[];
+	/** HTTP endpoints, each with the path its file position produced. */
+	endpoints?: Array<{ path: string; def: EndpointDefinition }>;
 	/**
 	 * Origins the template's Tailwind entry loads from, read off it at build
 	 * time. Every view imports that stylesheet, so every widget needs them.
@@ -127,61 +129,80 @@ function widgetError(name: string, error: unknown) {
 	};
 }
 
-function registerDocsTool(server: McpServer, docs: DocEntry[]) {
-	const corpus = docs.map((doc) => ({
-		...doc,
-		haystack: `${doc.title}\n${doc.body}`.toLowerCase(),
-	}));
+/**
+ * Answer anything outside the declared methods with 405 rather than running the
+ * handler. An endpoint is mounted with `use()`, which matches every method, so
+ * without this a `GET /api/cal/book` would reach a handler written for a POST
+ * body and fail somewhere less obvious.
+ */
+function methodGuard(allowed: string[]): RequestHandler {
+	// A preflight never carries the real method, and answering it 405 blocks the
+	// request it was asking about.
+	const pass = new Set([...allowed, "OPTIONS"]);
 
-	server.registerTool(
-		{
-			name: "search_docs",
-			title: "Search the documentation",
-			description:
-				"Search this product's documentation and answer general questions — pricing, eligibility, policies, how things work. Always search before answering, and answer only from what comes back. Never invent facts that are not in the results.",
-			inputSchema: { question: z.string().describe("The user's question, in their own words.") },
-			outputSchema: {
-				results: z.array(z.object({ slug: z.string(), title: z.string(), body: z.string() })),
-			},
-			annotations: annotations("Search the documentation", undefined, { readOnly: true }),
-		},
-		async ({ question }) => {
-			const terms = question
-				.toLowerCase()
-				.split(/[^a-z0-9]+/)
-				.filter((term) => term.length > 2);
+	return (req, res, next) => {
+		if (pass.has(req.method)) return next();
+		res.setHeader("Allow", allowed.join(", "));
+		res.status(405).json({ error: `${req.method} not allowed` });
+	};
+}
 
-			const results = corpus
-				.map((doc) => ({
-					doc,
-					score: terms.reduce((sum, term) => sum + (doc.haystack.includes(term) ? 1 : 0), 0),
-				}))
-				.filter(({ score }) => score > 0)
-				.sort((a, b) => b.score - a.score)
-				.slice(0, 3)
-				.map(({ doc }) => ({ slug: doc.slug, title: doc.title, body: doc.body }));
+/**
+ * The last link in every endpoint's chain: a 4-arity middleware, which is how
+ * Express recognises an error handler.
+ *
+ * Scoped to the endpoint's own mount path rather than the app, so it cannot
+ * catch anything the endpoint did not cause. Without it a rejected handler — or
+ * a malformed JSON body, which the parser reports the same way — reaches
+ * Express's default handler and answers an HTML error page to a `fetch()` that
+ * is waiting for JSON.
+ */
+function endpointErrorHandler(path: string): ErrorRequestHandler {
+	return (error, _req, res, next) => {
+		console.error(`[waniwani] endpoint "${path}" failed:`, error);
+		if (res.headersSent) return next(error);
+		// `express.json()` rejects a malformed body with a 400 already on the error.
+		const status = typeof (error as { status?: unknown })?.status === "number"
+			? (error as { status: number }).status
+			: 500;
+		res.status(status).json({
+			error: error instanceof Error ? error.message : "Internal server error",
+		});
+	};
+}
 
-			if (results.length === 0) {
-				const text = "Nothing in the documentation covers that question.";
-				return { structuredContent: { results: [] }, content: [{ type: "text" as const, text }] };
-			}
+/**
+ * Mount an app's HTTP endpoints on the server's Express app.
+ *
+ * Everything the framework does not do for us is done here, once, rather than
+ * left to each endpoint to remember: CORS (a widget calls from another origin),
+ * a JSON body parser (the framework installs none, so `req.body` would be
+ * `undefined`), the method guard, and the error envelope.
+ */
+function registerEndpoints(
+	server: McpServer,
+	endpoints: NonNullable<Manifest["endpoints"]>,
+): void {
+	for (const { path, def } of endpoints) {
+		const methods = def.method ? [def.method].flat().map((m) => m.toUpperCase()) : undefined;
 
-			return {
-				structuredContent: { results },
-				content: [
-					{
-						type: "text" as const,
-						text: results.map((r) => `## ${r.title}\n${r.body}`).join("\n\n---\n\n"),
-					},
-				],
-			};
-		},
-	);
+		const chain: Array<RequestHandler | ErrorRequestHandler> = [];
+		// The preflight answer names the methods the guard below actually accepts.
+		// Browsers cache it, so advertising a method that then answers 405 is a
+		// contradiction the widget author has to debug twice.
+		if (def.cors !== false) chain.push(cors(methods ? { methods } : undefined));
+		if (def.json !== false) chain.push(express.json());
+		if (methods) chain.push(methodGuard(methods));
+		chain.push(def.handler, endpointErrorHandler(path));
+
+		// The error handler's arity is what makes Express treat it as one, and
+		// `use()` is typed for request handlers only.
+		server.use(path, ...(chain as RequestHandler[]));
+	}
 }
 
 /**
- * Register an app's tools, widgets, flows, and docs onto a server the template
- * built.
+ * Register an app's tools, widgets and flows onto a server the template built.
  *
  * The template owns construction, its own tools, `withWaniwani`, and `run()`.
  * This adds to that server rather than replacing it, so a tool the template
@@ -189,7 +210,13 @@ function registerDocsTool(server: McpServer, docs: DocEntry[]) {
  * app's own tools sit alongside it.
  */
 export async function registerApp(server: McpServer, manifest: Manifest): Promise<McpServer> {
-	const { tools, widgets, flows, docs, styleDomains = [] } = manifest;
+	const { tools, widgets, flows, endpoints = [], styleDomains = [] } = manifest;
+
+	// Before the tools, because Express matches in registration order and the
+	// framework mounts `/mcp` after this function returns. Nothing here can
+	// shadow it — `/api/...` and `/mcp` do not overlap — but the ordering is the
+	// reason an endpoint is reachable at all.
+	registerEndpoints(server, endpoints);
 
 	// Widgets: one `data` schema drives the input schema, the structured output,
 	// and the type the component receives.
@@ -274,10 +301,6 @@ export async function registerApp(server: McpServer, manifest: Manifest): Promis
 		server.registerTool({ ...flow.config, name: flow.name }, flow.handler);
 	}
 
-	if (docs.length > 0) {
-		registerDocsTool(server, docs);
-	}
-
 	// `withWaniwani` is deliberately not called here. It wraps every registered
 	// handler in place, so it has to run after the last registration — which is
 	// the template's, not this function's. `src/server.ts` calls it.

package/cli/account.mjs

@@ -1,264 +0,0 @@
-/**
- * The WaniWani account boundary.
- *
- * `tunnel` is the one command in this CLI that talks to app.waniwani.ai, and it
- * needs two facts: who the developer is, and which agent this repo is bound to.
- * Both already have a home that `@waniwani/cli` writes and `@waniwani/sdk`
- * reads, so this file invents no third place to look:
- *
- *   ~/.config/waniwani/settings.json   credentials and the instance they were
- *                                      issued for. One login per machine, mode
- *                                      0600, honours XDG_CONFIG_HOME.
- *   ./waniwani.json                    orgId, projectId, apiUrl, devPort. The
- *                                      file `waniwani connect` writes, and the
- *                                      one the SDK loads at runtime.
- *
- * `.waniwani/` holds neither of them. In the kit that directory is build output:
- * every command regenerates it, the app's .gitignore covers it, and `eject` says
- * to delete it. A refresh token written there lasts until the next `waniwani
- * dev`. This is the same reasoning that moved the login CLI's own credentials
- * out of it.
- *
- * `WANIWANI_API_KEY` is ignored here on purpose. A kit app usually carries that
- * key for tracking, where it is scoped to the project's production environment,
- * while the tunnel and dev-session routes are about the human at the terminal.
- * Auth is therefore the OAuth token, refreshed in place when it has aged out.
- */
-
-import { spawn } from "node:child_process";
-import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { dim } from "./log.mjs";
-
-const DEFAULT_API_URL = "https://app.waniwani.ai";
-
-const CONFIG_HOME = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
-const SETTINGS_FILE = join(CONFIG_HOME, "waniwani", "settings.json");
-const DIR_MODE = 0o700;
-const FILE_MODE = 0o600;
-
-/** A token this close to expiry is treated as expired, so a long run doesn't 401 mid-flight. */
-const EXPIRY_SKEW_MS = 5 * 60 * 1000;
-
-/**
- * The CLI that owns logging in and binding a repo to an agent.
- *
- * Those two flows are an OAuth2 PKCE round trip with a local callback server,
- * and a pair of pickers over the org's agents. Both live in `@waniwani/cli`
- * already, and both write exactly the files above, so this CLI drives it for
- * them instead of carrying a second copy that has to stay in step.
- */
-const LOGIN_CLI = "@waniwani/cli";
-
-function readSettings() {
-	try {
-		return JSON.parse(readFileSync(SETTINGS_FILE, "utf-8"));
-	} catch {
-		return {};
-	}
-}
-
-function writeSettings(settings) {
-	mkdirSync(dirname(SETTINGS_FILE), { recursive: true, mode: DIR_MODE });
-	writeFileSync(SETTINGS_FILE, JSON.stringify(settings, null, "\t"));
-	chmodSync(SETTINGS_FILE, FILE_MODE);
-}
-
-/**
- * The repo's `waniwani.json`, or null when it has never been connected.
- *
- * Only the JSON file counts. An app folder also has a `waniwani.config.ts`, and
- * in the kit that is the app itself (`defineApp`), which has nothing to say
- * about org or agent ids.
- */
-export function readProjectConfig(appRoot) {
-	const file = join(appRoot, "waniwani.json");
-	if (!existsSync(file)) return null;
-	try {
-		return JSON.parse(readFileSync(file, "utf-8"));
-	} catch (error) {
-		throw new Error(`${file} is not valid JSON: ${error.message}`);
-	}
-}
-
-/** Which instance to talk to, most specific wins. Mirrors the login CLI's order. */
-function resolveApiUrl(project) {
-	return process.env.WANIWANI_API_URL || project?.apiUrl || readSettings().apiUrl || DEFAULT_API_URL;
-}
-
-function isExpired(settings) {
-	if (!settings.expiresAt) return true;
-	return new Date(settings.expiresAt).getTime() - EXPIRY_SKEW_MS < Date.now();
-}
-
-/**
- * Trade the refresh token for a new access token and persist both.
- *
- * `resource` is RFC 8707 and load-bearing: without it the OAuth server issues an
- * opaque token, which then fails JWKS validation on every API call.
- */
-async function refreshTokens(apiUrl) {
-	const settings = readSettings();
-	if (!settings.refreshToken || !settings.clientId) return null;
-
-	const response = await fetch(`${apiUrl}/api/auth/oauth2/token`, {
-		method: "POST",
-		headers: { "Content-Type": "application/x-www-form-urlencoded" },
-		body: new URLSearchParams({
-			grant_type: "refresh_token",
-			refresh_token: settings.refreshToken,
-			client_id: settings.clientId,
-			resource: apiUrl,
-		}).toString(),
-	});
-	if (!response.ok) return null;
-
-	const tokens = await response.json();
-	writeSettings({
-		...settings,
-		accessToken: tokens.access_token,
-		refreshToken: tokens.refresh_token,
-		expiresAt: new Date(Date.now() + tokens.expires_in * 1000).toISOString(),
-	});
-	return tokens.access_token;
-}
-
-/**
- * The stored token when it is usable against `apiUrl`, else null.
- *
- * A token issued for another instance counts as no token at all: the US and EU
- * deployments have separate identities, so carrying one over produces a 401 that
- * reads like a broken account.
- */
-async function usableToken(apiUrl) {
-	const settings = readSettings();
-	if (!settings.accessToken) return null;
-	if (settings.apiUrl && settings.apiUrl !== apiUrl) return null;
-	if (!isExpired(settings)) return settings.accessToken;
-	return refreshTokens(apiUrl);
-}
-
-/** The login CLI's entry file when it is installed alongside us, else null. */
-function localLoginCli() {
-	try {
-		return fileURLToPath(import.meta.resolve(LOGIN_CLI));
-	} catch {
-		return null;
-	}
-}
-
-/**
- * Hand the terminal to the login CLI for one subcommand.
- *
- * An installed copy is run through `node` by absolute path. Both packages
- * publish a `waniwani` binary, so going through `node_modules/.bin` would leave
- * it to install order which of the two answers.
- */
-async function runLoginCli(subcommand) {
-	const entry = localLoginCli();
-	const [command, args] = entry
-		? [process.execPath, [entry, subcommand]]
-		: ["npx", ["-y", `${LOGIN_CLI}@latest`, subcommand]];
-
-	console.log(dim(`[waniwani] running ${LOGIN_CLI} ${subcommand}…`));
-	const code = await new Promise((resolve) => {
-		const child = spawn(command, args, { stdio: "inherit" });
-		child.on("close", (exit) => resolve(exit ?? 1));
-		child.on("error", () => resolve(1));
-	});
-	if (code !== 0) {
-		throw new Error(`\`waniwani ${subcommand}\` exited with code ${code}`);
-	}
-}
-
-/**
- * Resolve the account this repo runs against, filling in whatever is missing.
- *
- * A machine with no credentials gets the login flow, and a repo with no
- * `waniwani.json` gets the connect flow, both in the terminal the user is
- * already sitting in. When they come back the files are on disk and every later
- * run of this command is silent.
- */
-export async function connectAccount(appRoot) {
-	let project = readProjectConfig(appRoot);
-	let apiUrl = resolveApiUrl(project);
-
-	if (!(await usableToken(apiUrl))) {
-		await runLoginCli("login");
-		project = readProjectConfig(appRoot);
-		apiUrl = resolveApiUrl(project);
-		if (!(await usableToken(apiUrl))) {
-			throw new Error(`no credentials at ${SETTINGS_FILE} after logging in`);
-		}
-	}
-
-	if (!project?.projectId) {
-		await runLoginCli("connect");
-		project = readProjectConfig(appRoot);
-	}
-	if (!project?.projectId) {
-		throw new Error(`no projectId in ${join(appRoot, "waniwani.json")}: run \`waniwani connect\` to bind this repo to an agent`);
-	}
-
-	return {
-		apiUrl,
-		projectId: project.projectId,
-		devPort: project.devPort,
-		playgroundUrl: `${apiUrl}/agents/${project.projectId}/playground?localMode=1`,
-	};
-}
-
-/**
- * An authenticated client for one instance.
- *
- * Responses come back in the API's `{ success, data, error }` envelope, so the
- * payload is unwrapped here and a failure is raised as an ordinary Error the
- * CLI's top-level handler prints. A 401 buys one refresh and one retry, which
- * covers a token that aged out during a long dev session.
- */
-export function createClient(apiUrl) {
-	const send = async (method, path, body, retry = true) => {
-		const token = await usableToken(apiUrl);
-		if (!token) {
-			throw new Error("not logged in: run `waniwani login`");
-		}
-
-		const response = await fetch(`${apiUrl}${path}`, {
-			method,
-			headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
-			body: body === undefined ? undefined : JSON.stringify(body),
-		});
-
-		if (response.status === 204) return undefined;
-
-		const text = await response.text();
-		let payload;
-		try {
-			payload = JSON.parse(text);
-		} catch {
-			throw new Error(`${method} ${path} failed with ${response.status}: ${text.slice(0, 200)}`);
-		}
-
-		if (response.ok && !payload.error) return payload.data;
-
-		if (response.status === 401 && retry && (await refreshTokens(apiUrl))) {
-			return send(method, path, body, false);
-		}
-
-		const error = payload.error;
-		const message =
-			(typeof error === "object" && error?.message) ||
-			payload.message ||
-			(typeof error === "string" ? error : null) ||
-			`${method} ${path} failed with ${response.status}`;
-		throw new Error(message);
-	};
-
-	return {
-		post: (path, body) => send("POST", path, body),
-		patch: (path) => send("PATCH", path),
-		delete: (path) => send("DELETE", path),
-	};
-}

package/cli/tunnel.mjs

@@ -1,140 +0,0 @@
-/**
- * A public hostname for a dev server on this machine.
- *
- * The MCP endpoint has to be reachable from the internet before anything else
- * can drive it: the WaniWani chat backend runs on Vercel and cannot see
- * `localhost`, and neither can Claude Desktop or ChatGPT. Cloudflare answers
- * that with a named tunnel per agent, provisioned server-side at agent creation,
- * so the hostname is `<slug>.waniwani.dev` and stays that way across runs and is
- * safe to paste into an MCP client's config.
- *
- * The API owns the pairing: it repoints the tunnel's ingress at the port passed
- * to it, then mints a connector token for that one tunnel. This file runs
- * cloudflared against the token and reports when the edge has the connection.
- */
-
-import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
-import { createServer } from "node:net";
-
-const TUNNEL_READY_TIMEOUT_MS = 30_000;
-const SERVER_READY_TIMEOUT_MS = 30_000;
-const SERVER_POLL_MS = 500;
-
-/**
- * Bind the wildcard, matching how a Node server binds, so a listener already on
- * `::` or `0.0.0.0` reads as a conflict. A check against 127.0.0.1 misses those.
- */
-export function isPortAvailable(port) {
-	return new Promise((resolve) => {
-		const server = createServer();
-		server.once("error", () => resolve(false));
-		server.once("listening", () => server.close(() => resolve(true)));
-		server.listen(port);
-	});
-}
-
-/** The first free port at or above `start`. */
-export async function findAvailablePort(start, attempts = 20) {
-	for (let port = start; port < start + attempts; port++) {
-		if (await isPortAvailable(port)) return port;
-	}
-	throw new Error(`no free port between ${start} and ${start + attempts - 1}`);
-}
-
-/**
- * Wait until something answers on `url`.
- *
- * Any response counts, including a 404: the question is whether the dev server
- * has the port, and the tunnel's ingress is pointed at it before it does.
- */
-export async function waitForLocalServer(url, timeoutMs = SERVER_READY_TIMEOUT_MS) {
-	const deadline = Date.now() + timeoutMs;
-	while (Date.now() < deadline) {
-		try {
-			await fetch(url);
-			return;
-		} catch {
-			await new Promise((resolve) => setTimeout(resolve, SERVER_POLL_MS));
-		}
-	}
-	throw new Error(`the dev server did not answer on ${url} within ${timeoutMs / 1000}s`);
-}
-
-/**
- * Resolve the cloudflared wrapper at call time.
- *
- * It is an optional dependency, and its install step fetches a platform binary
- * that a CI image or a container build has no use for. A static import would
- * make the whole CLI fail to load wherever that install was skipped, so the cost
- * lands on the one command that needs it.
- */
-async function loadCloudflared() {
-	try {
-		return await import("cloudflared");
-	} catch {
-		throw new Error(
-			"the tunnel needs the `cloudflared` package, which is not installed.\n" +
-				"  It ships as an optional dependency, so an install run with --omit=optional skips it.\n" +
-				"  Add it with `npm install cloudflared`.",
-		);
-	}
-}
-
-/** The package ships a wrapper, so the binary itself is fetched on first use. */
-async function cloudflaredBinary() {
-	const { bin, install } = await loadCloudflared();
-	if (!existsSync(bin)) await install(bin);
-	return bin;
-}
-
-/**
- * Run the agent's named tunnel under a connector token.
- *
- * The token encodes which tunnel to serve and the ingress was set when it was
- * issued, so there is no `--url` to pass. Resolution waits for cloudflared to
- * confirm an edge connection, since anything earlier races traffic against
- * connector readiness.
- */
-export async function startNamedTunnel({ hostname, token }) {
-	const bin = await cloudflaredBinary();
-	const child = spawn(bin, ["tunnel", "--no-autoupdate", "run", "--token", token], {
-		stdio: ["ignore", "pipe", "pipe"],
-	});
-
-	return new Promise((resolve, reject) => {
-		let settled = false;
-		const settle = (fn, value) => {
-			if (settled) return;
-			settled = true;
-			clearTimeout(timer);
-			fn(value);
-		};
-
-		const timer = setTimeout(() => {
-			child.kill("SIGTERM");
-			settle(reject, new Error(`cloudflared did not connect within ${TUNNEL_READY_TIMEOUT_MS / 1000}s`));
-		}, TUNNEL_READY_TIMEOUT_MS);
-
-		// cloudflared logs this line on each successful edge handshake, and the
-		// first one means the hostname is serving traffic.
-		const onOutput = (chunk) => {
-			if (chunk.toString().includes("Registered tunnel connection")) {
-				settle(resolve, {
-					hostname,
-					publicUrl: `https://${hostname}`,
-					stop: () => {
-						if (child.exitCode === null) child.kill("SIGTERM");
-					},
-				});
-			}
-		};
-
-		child.stdout?.on("data", onOutput);
-		child.stderr?.on("data", onOutput);
-		child.once("error", (error) => settle(reject, error));
-		child.once("exit", (code) => {
-			settle(reject, new Error(`cloudflared exited with code ${code ?? "unknown"} before connecting`));
-		});
-	});
-}