@waniwani/kit 0.1.0

package/cli/log.mjs

@@ -0,0 +1,177 @@
+/** Build output formatting. Errors point at a file and say how to fix it. */
+
+/** ESC by char code: a raw control byte in source is invisible and fragile. */
+const ESC = String.fromCharCode(27);
+
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const wrap = (code) => (text) => (useColor ? `${ESC}[${code}m${text}${ESC}[0m` : text);
+
+export const red = wrap("31");
+export const green = wrap("32");
+export const yellow = wrap("33");
+export const dim = wrap("2");
+export const bold = wrap("1");
+
+/**
+ * The wordmark, at half the height of the art `waniwani login` prints.
+ *
+ * Same letterforms: the tall version is six rows of full blocks with a box-glyph
+ * drop shadow, and each row here folds two of those together — `▀` where only
+ * the upper row had ink, `▄` where only the lower did, `█` where both. Three
+ * rows instead of six, at the same width, and nothing about the shapes changes.
+ *
+ * One colour per row rather than per glyph: a vertical ramp needs three escape
+ * sequences instead of two hundred, and reads the same.
+ */
+const LOGO = [
+	"██     ██ ▄█▀▀▀█▄ ███▄   ██  ██  ██     ██ ▄█▀▀▀█▄ ███▄   ██  ██",
+	"██ ▄█▄ ██ ██▀▀▀██ ██ ▀█▄ ██  ██  ██ ▄█▄ ██ ██▀▀▀██ ██ ▀█▄ ██  ██",
+	" ▀▀▀ ▀▀▀  ▀▀   ▀▀ ▀▀   ▀▀▀▀  ▀▀   ▀▀▀ ▀▀▀  ▀▀   ▀▀ ▀▀   ▀▀▀▀  ▀▀",
+];
+
+const LOGO_WIDTH = 65;
+
+/** The brand accent, `#04d916`. */
+const ACCENT = [4, 217, 22];
+
+/** How far the first and last rows are mixed toward white and black. */
+const LIGHTEN = 0.42;
+const DARKEN = 0.35;
+
+/**
+ * The ramp stop for one row: a tint of the accent at the top, the accent itself
+ * in the middle, a shade of it at the bottom — so the wordmark reads as one
+ * object lit from above.
+ *
+ * Interpolated from the row count rather than written out, so the art and the
+ * ramp cannot drift apart when either changes.
+ */
+function rampStop(index, rows) {
+	// -1 on the first row, 0 in the middle, +1 on the last.
+	const position = rows === 1 ? 0 : (index / (rows - 1)) * 2 - 1;
+	if (position <= 0) {
+		const mix = LIGHTEN * -position;
+		return ACCENT.map((channel) => Math.round(channel + (255 - channel) * mix));
+	}
+	return ACCENT.map((channel) => Math.round(channel * (1 - DARKEN * position)));
+}
+
+/** 24-bit colour is used only where the terminal says it has it. */
+const truecolor = ["truecolor", "24bit"].includes(process.env.COLORTERM ?? "");
+
+/** The six levels each channel can take in the xterm 256-colour cube. */
+const CUBE_LEVELS = [0, 95, 135, 175, 215, 255];
+
+/** The nearest cube entry, for a terminal that does not announce 24-bit colour. */
+function cube([r, g, b]) {
+	const nearest = (channel) =>
+		CUBE_LEVELS.reduce(
+			(best, _, index) =>
+				Math.abs(CUBE_LEVELS[index] - channel) < Math.abs(CUBE_LEVELS[best] - channel) ? index : best,
+			0,
+		);
+	return 16 + 36 * nearest(r) + 6 * nearest(g) + nearest(b);
+}
+
+/** The foreground escape for one row of the ramp. */
+function ramp(index, rows) {
+	const rgb = rampStop(index, rows);
+	if (!truecolor) {
+		return `${ESC}[38;5;${cube(rgb)}m`;
+	}
+	return `${ESC}[38;2;${rgb.join(";")}m`;
+}
+
+/**
+ * Print the banner a command opens with.
+ *
+ * The art needs 65 columns and a terminal that wants colour. A narrower one, a
+ * pipe, a CI log or `NO_COLOR` gets the wordmark on one line instead — the same
+ * information, and nothing that turns into wrapped garbage in a build log.
+ */
+export function banner(version) {
+	// `||`, not `??`: a pty whose window size was never set reports 0 columns,
+	// which is unknown rather than narrow.
+	const columns = process.stdout.columns || 80;
+	if (!useColor || columns < LOGO_WIDTH) {
+		// The wordmark still carries the accent — it is the same banner, narrowed.
+		const mark = useColor ? `${ramp(0, 1)}${ESC}[1mwaniwani${ESC}[0m` : "waniwani";
+		console.log(`\n${mark} ${dim(`v${version}`)}`);
+		return;
+	}
+	console.log("");
+	for (const [index, line] of LOGO.entries()) {
+		console.log(`${ramp(index, LOGO.length)}${line}${ESC}[0m`);
+	}
+	console.log(dim(`v${version}`.padStart(LOGO_WIDTH)));
+	console.log("");
+}
+
+/**
+ * One URL a command hands the developer, in the shape every command uses for
+ * them. The label is padded so a list of endpoints aligns whether the framework
+ * printed the line or this CLI did.
+ */
+export function endpoint(label, url) {
+	return `  ${dim(label.padEnd(8))} ${green(url)}`;
+}
+
+function printGroup(entries, marker, color) {
+	const byFile = new Map();
+	for (const entry of entries) {
+		const list = byFile.get(entry.where) ?? [];
+		list.push(entry);
+		byFile.set(entry.where, list);
+	}
+
+	for (const [where, list] of byFile) {
+		console.log(`  ${bold(where)}`);
+		for (const entry of list) {
+			console.log(`  ${color(marker)} ${entry.message}`);
+			if (entry.hint) {
+				console.log(`    ${dim(entry.hint)}`);
+			}
+		}
+		console.log("");
+	}
+}
+
+export function printReport(app, report) {
+	if (!report.ok) {
+		console.log(`\n${red("✗")} ${bold("Build check failed")}\n`);
+		printGroup(report.errors, "└", red);
+		if (report.warnings.length > 0) {
+			printGroup(report.warnings, "└", yellow);
+		}
+		return;
+	}
+
+	const counts = [
+		[app.widgets.length, "widget"],
+		[app.tools.length, "tool"],
+		[app.flows.length, "flow"],
+		[app.docs.length, "doc"],
+	]
+		.filter(([count]) => count > 0)
+		.map(([count, label]) => `${count} ${label}${count === 1 ? "" : "s"}`);
+
+	console.log(`${green("✓")} ${bold("Build check passed")} ${dim(`— ${counts.join(", ")}`)}`);
+
+	for (const widget of app.widgets) {
+		console.log(`  ${dim("widget")} ${widget.name}`);
+	}
+	for (const tool of app.tools) {
+		console.log(`  ${dim("tool  ")} ${tool.name}`);
+	}
+	for (const flow of app.flows) {
+		console.log(`  ${dim("flow  ")} ${flow.name}`);
+	}
+	if (app.docs.length > 0) {
+		console.log(`  ${dim("tool  ")} search_docs ${dim(`(${app.docs.length} pages)`)}`);
+	}
+
+	if (report.warnings.length > 0) {
+		console.log("");
+		printGroup(report.warnings, "└", yellow);
+	}
+}

package/cli/scan.mjs

@@ -0,0 +1,84 @@
+/**
+ * Discover an app by walking its folders. Convention, not configuration.
+ *
+ *   waniwani.config.ts
+ *   tools/<name>.ts
+ *   widgets/<name>/{widget.ts,ui.tsx}
+ *   flows/<name>.ts
+ *   docs/<slug>.md
+ *
+ * There is no CSS in that list. Styling is Tailwind, from the distribution
+ * template's `src/index.css` — its `@theme` tokens and its `dark` variant — and
+ * a widget writes utility classes in `ui.tsx`. Stray `styles.css` files are
+ * collected only so the build check can tell an author they are dead.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, extname, join } from "node:path";
+
+const CODE_EXT = new Set([".ts", ".tsx", ".mts"]);
+
+function listFiles(dir) {
+	if (!existsSync(dir)) return [];
+	return readdirSync(dir)
+		.filter((entry) => !entry.startsWith(".") && !entry.startsWith("_"))
+		.map((entry) => join(dir, entry))
+		.filter((path) => statSync(path).isFile());
+}
+
+function listDirs(dir) {
+	if (!existsSync(dir)) return [];
+	return readdirSync(dir)
+		.filter((entry) => !entry.startsWith(".") && !entry.startsWith("_"))
+		.map((entry) => join(dir, entry))
+		.filter((path) => statSync(path).isDirectory());
+}
+
+function stripExt(path) {
+	return basename(path, extname(path));
+}
+
+/** `# Title` on the first heading line, falling back to the slug. */
+function docTitle(body, slug) {
+	const heading = body.split("\n").find((line) => line.startsWith("# "));
+	return heading ? heading.slice(2).trim() : slug;
+}
+
+export function scanApp(root) {
+	const configFile = [join(root, "waniwani.config.ts"), join(root, "waniwani.config.js")].find(
+		existsSync,
+	);
+
+	const tools = listFiles(join(root, "tools"))
+		.filter((file) => CODE_EXT.has(extname(file)))
+		.map((file) => ({ name: stripExt(file), file }));
+
+	const widgets = listDirs(join(root, "widgets")).map((dir) => {
+		const name = basename(dir);
+		const contract = [join(dir, "widget.ts"), join(dir, "widget.tsx")].find(existsSync);
+		const ui = [join(dir, "ui.tsx"), join(dir, "ui.jsx")].find(existsSync);
+		return { name, dir, contract, ui };
+	});
+
+	const flows = listFiles(join(root, "flows"))
+		.filter((file) => CODE_EXT.has(extname(file)))
+		.map((file) => ({ name: stripExt(file), file }));
+
+	const docs = listFiles(join(root, "docs"))
+		.filter((file) => extname(file) === ".md")
+		.map((file) => {
+			const slug = stripExt(file);
+			const body = readFileSync(file, "utf-8").trim();
+			return { slug, file, title: docTitle(body, slug), body };
+		});
+
+	// The two paths an author is most likely to expect the kit to pick up. It
+	// imports neither, so a file at either one is styling that never reaches the
+	// browser — the kind of silent no-op the build check exists to name.
+	const strayStyles = [
+		join(root, "styles.css"),
+		...widgets.map((widget) => join(widget.dir, "styles.css")),
+	].filter(existsSync);
+
+	return { root, configFile, tools, widgets, flows, docs, strayStyles };
+}

package/cli/template.mjs

@@ -0,0 +1,152 @@
+/**
+ * Resolve the distribution template.
+ *
+ * The template is a separate public repo, consumed as-is. Nothing is forked
+ * into this package: the generator downloads the repo at a pinned commit,
+ * caches it, and copies the plumbing out of it. What ships to customers is the
+ * same tree anyone can read on GitHub, clone, and deploy by hand.
+ *
+ * Sources:
+ *   github:OWNER/REPO#REF   a GitHub repo at a branch, tag, or SHA (default)
+ *   /path/to/checkout       a local clone, for working on the template itself
+ *
+ * Override per command with `--template <source>` or `WANIWANI_TEMPLATE`.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+
+/**
+ * `beta`, not `main`. The generator is written against the template's current
+ * layout — `vite.config.ts`, `src/server.ts`, `src/views/` — and `main` is still
+ * the older `server/` + `web/` + `api/` split, which it cannot absorb. When beta
+ * merges down, this goes back to a ref on `main` (a tag, ideally — see the
+ * README's known gaps).
+ */
+export const DEFAULT_TEMPLATE = "github:WaniWani-AI/mcp-distribution-template#beta";
+
+const CACHE_ROOT = join(homedir(), ".cache", "waniwani", "templates");
+
+/** `github:owner/repo#ref` -> its parts. */
+function parseGithub(source) {
+	const match = /^github:([^/]+)\/([^#]+)(?:#(.+))?$/.exec(source);
+	if (!match) return null;
+	return { owner: match[1], repo: match[2], ref: match[3] ?? "main" };
+}
+
+/**
+ * Resolve a ref to a commit SHA, so a cache entry is content-addressed and two
+ * builds of the same ref cannot silently differ.
+ */
+async function resolveSha({ owner, repo, ref }) {
+	let response;
+	try {
+		response = await fetch(`https://api.github.com/repos/${owner}/${repo}/commits/${ref}`, {
+			headers: { Accept: "application/vnd.github.sha" },
+		});
+	} catch (cause) {
+		// Unreachable network. A cached template is a reasonable answer.
+		throw Object.assign(new Error(`cannot reach GitHub: ${cause.message}`), { offline: true });
+	}
+
+	// A bad ref is the caller's mistake, not a network problem — falling back
+	// to a cached template here would hide the typo.
+	if (!response.ok) {
+		throw new Error(
+			`GitHub returned ${response.status} for ${owner}/${repo}@${ref}` +
+				(response.status === 404 ? " — check the repo name and ref, or that it is public" : ""),
+		);
+	}
+	return (await response.text()).trim();
+}
+
+async function download({ owner, repo, sha }, destination) {
+	const response = await fetch(
+		`https://codeload.github.com/${owner}/${repo}/tar.gz/${sha}`,
+	);
+	if (!response.ok) {
+		throw new Error(`could not download ${owner}/${repo}@${sha}: ${response.status}`);
+	}
+
+	const archive = join(tmpdir(), `waniwani-template-${sha}.tar.gz`);
+	writeFileSync(archive, Buffer.from(await response.arrayBuffer()));
+
+	// Extract into a staging directory first, so an interrupted run cannot
+	// leave a half-populated cache entry that later builds would trust.
+	const staging = `${destination}.partial`;
+	rmSync(staging, { recursive: true, force: true });
+	mkdirSync(staging, { recursive: true });
+
+	const result = spawnSync("tar", ["-xzf", archive, "-C", staging, "--strip-components=1"]);
+	rmSync(archive, { force: true });
+	if (result.status !== 0) {
+		rmSync(staging, { recursive: true, force: true });
+		throw new Error(`could not extract the template archive: ${result.stderr?.toString().trim()}`);
+	}
+
+	rmSync(destination, { recursive: true, force: true });
+	spawnSync("mv", [staging, destination]);
+}
+
+/** The newest cache entry for a repo, used when the network is unavailable. */
+function newestCached(owner, repo) {
+	if (!existsSync(CACHE_ROOT)) return null;
+	const prefix = `${owner}-${repo}-`;
+	const entries = readdirSync(CACHE_ROOT)
+		.filter((name) => name.startsWith(prefix))
+		.map((name) => ({ name, mtime: statSync(join(CACHE_ROOT, name)).mtimeMs }))
+		.sort((a, b) => b.mtime - a.mtime);
+	return entries[0] ? join(CACHE_ROOT, entries[0].name) : null;
+}
+
+/**
+ * @param source `github:owner/repo#ref` or a local path
+ * @returns `{ dir, source, ref, sha, cached, local }`
+ */
+export async function resolveTemplate(source = DEFAULT_TEMPLATE) {
+	const github = parseGithub(source);
+
+	if (!github) {
+		const dir = resolve(source);
+		if (!existsSync(dir)) {
+			throw new Error(`template not found: ${dir}`);
+		}
+		return { dir, source, local: true };
+	}
+
+	const { owner, repo, ref } = github;
+	mkdirSync(CACHE_ROOT, { recursive: true });
+
+	let sha;
+	try {
+		sha = await resolveSha(github);
+	} catch (error) {
+		const fallback = error.offline && newestCached(owner, repo);
+		if (!fallback) throw error;
+		return {
+			dir: fallback,
+			source,
+			ref,
+			sha: fallback.split("-").pop(),
+			cached: true,
+			offline: true,
+		};
+	}
+
+	const dir = join(CACHE_ROOT, `${owner}-${repo}-${sha}`);
+	const cached = existsSync(dir);
+	if (!cached) {
+		await download({ owner, repo, sha }, dir);
+	}
+
+	return { dir, source, ref, sha, cached };
+}
+
+/** One-line description of what a build used, for logs and provenance files. */
+export function describeTemplate(template) {
+	if (template.local) return `${template.dir} (local)`;
+	const state = template.offline ? "offline, cached" : template.cached ? "cached" : "downloaded";
+	return `${template.source} @ ${template.sha?.slice(0, 7)} (${state})`;
+}

package/cli/tunnel.mjs

@@ -0,0 +1,140 @@
+/**
+ * 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`));
+		});
+	});
+}