@waniwani/kit 0.1.6 → 0.1.7

package/cli/template.mjs

@@ -1,190 +0,0 @@
-/**
- * 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";
-
-/**
- * A commit, not a branch.
- *
- * A published version of this package is frozen, and what it generates has to
- * be frozen with it. While the default was `beta`, the ref was re-resolved on
- * the customer's machine at every command, so a push to that branch changed the
- * output of every installed copy, and the assertions that catch a layout move
- * (`REQUIRED` and `assertSeam` in `./codegen.mjs`) fired in a customer's
- * terminal. Pinning a commit moves that failure into this repo's CI, where
- * `scripts/template-contract.mjs` builds a real app against the pin before a
- * release goes out.
- *
- * Bumping it is a one-line diff, and `scripts/bump-deps.mjs` proposes it. The
- * commit is on the template's `beta` branch: the generator is written against
- * that branch's layout (`vite.config.ts`, `src/server.ts`, `src/views/`), and
- * `main` is still the older `server/` + `web/` + `api/` split, which it cannot
- * absorb. An annotated tag can replace the SHA here whenever the template grows
- * one, with no change to the resolver.
- *
- * This commit is `beta`'s head, and it reads `search` and `tracking` off
- * `src/waniwani.ts` — the two fields `generateServerApp` emits from the app's
- * `defineApp({ ... })`. That pairing is the reason to bump the two together:
- * moving the pin here without the generator emitting those fields compiles to
- * TS2339, and the contract is what catches it.
- *
- * Working on the template itself does not need a release: pass `--template` or
- * set `WANIWANI_TEMPLATE` to a branch ref or a local checkout.
- */
-export const DEFAULT_TEMPLATE =
-	"github:WaniWani-AI/mcp-distribution-template#c0d00e72a3733a5f42389731fe6bbaf7e0e07863";
-
-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" };
-}
-
-/** A full commit SHA, which is already the thing a ref has to be resolved to. */
-function isSha(ref) {
-	return /^[0-9a-f]{40}$/i.test(ref);
-}
-
-/**
- * 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 }) {
-	// The pinned default is a commit, and asking the API to resolve a commit to
-	// itself is a round trip that can rate-limit, fail, or go down. A cached
-	// pin then needs no network at all, which is the point of pinning.
-	if (isSha(ref)) return ref.toLowerCase();
-
-	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";
-	// A pinned source already carries the commit, so printing the source verbatim
-	// would repeat all 40 characters of it next to the short form. Collapse to
-	// the repo, and say that the commit came from a pin rather than a branch.
-	const github = parseGithub(template.source);
-	const pinned = github && isSha(github.ref);
-	const origin = pinned ? `github:${github.owner}/${github.repo}` : template.source;
-	return `${origin} @ ${template.sha?.slice(0, 7)} (${pinned ? `pinned, ${state}` : state})`;
-}

package/cli/validate.mjs

@@ -1,391 +0,0 @@
-/**
- * The build check.
- *
- * Structural rules first (cheap, from the filesystem), then the modules are
- * actually imported so a broken export or a flow that fails to compile is
- * reported here rather than as a stack trace at request time.
- */
-
-import { readFileSync } from "node:fs";
-import { join, relative } from "node:path";
-import { loadAppEnv } from "./env.mjs";
-import { compare, floorOf, installable } from "./peers.mjs";
-
-const NAME_RE = /^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?$/;
-
-/**
- * What may appear in an endpoint path segment. Deliberately narrower than what
- * a filesystem allows: the segment becomes a URL path, and a file called
- * `Book Call.ts` would be served at a URL nobody would guess.
- */
-const SEGMENT_RE = /^[a-zA-Z0-9._-]+$/;
-
-const HTTP_METHODS = new Set(["get", "post", "put", "patch", "delete", "head", "options"]);
-
-class Report {
-	constructor(root) {
-		this.root = root;
-		this.errors = [];
-		this.warnings = [];
-	}
-
-	error(where, message, hint) {
-		this.errors.push({ where, message, hint });
-	}
-
-	warn(where, message, hint) {
-		this.warnings.push({ where, message, hint });
-	}
-
-	get ok() {
-		return this.errors.length === 0;
-	}
-}
-
-function rel(root, file) {
-	return relative(root, file) || ".";
-}
-
-/** Everything the filesystem alone can tell us. */
-function checkStructure(app, report) {
-	const { root } = app;
-
-	if (!app.configFile) {
-		report.error(
-			"waniwani.config.ts",
-			"missing app config",
-			"create waniwani.config.ts with `export default defineApp({ name: '...' })`",
-		);
-	}
-
-	if (app.tools.length + app.widgets.length + app.flows.length === 0) {
-		report.error(
-			".",
-			"this app exposes nothing",
-			"add a tool (tools/<name>.ts), a widget (widgets/<name>/), or a flow (flows/<name>.ts)",
-		);
-	}
-
-	for (const widget of app.widgets) {
-		const where = rel(root, widget.dir);
-		if (!widget.contract) {
-			report.error(
-				where,
-				"missing widget.ts",
-				"every widget folder needs a widget.ts with `export default defineWidget({ ... })`",
-			);
-		}
-		if (!widget.ui) {
-			report.error(
-				where,
-				"missing ui.tsx",
-				"every widget folder needs a ui.tsx with a default-exported React component",
-			);
-		}
-	}
-
-	// Styling is Tailwind, out of the template's `src/index.css`. Nothing imports
-	// an app's own CSS, so a styles.css is a file whose rules never load — and it
-	// fails in the worst way, by rendering an unstyled widget rather than an
-	// error. Naming it here costs one deletion; missing it costs a debugging
-	// session against a bundle that never mentions the file.
-	for (const file of app.strayStyles) {
-		report.error(
-			rel(root, file),
-			"app CSS is not bundled — nothing imports this file",
-			"style with Tailwind utility classes in ui.tsx; the template's src/index.css carries the @theme tokens and the `dark` variant",
-		);
-	}
-
-	// A widget's folder name is its MCP tool name and its bundle entry name, so
-	// it has to survive both.
-	const named = [
-		...app.tools.map((t) => ({ kind: "tool", name: t.name, where: rel(root, t.file) })),
-		...app.widgets.map((w) => ({ kind: "widget", name: w.name, where: rel(root, w.dir) })),
-	];
-
-	const seen = new Map();
-	for (const entry of named) {
-		if (!NAME_RE.test(entry.name)) {
-			report.error(
-				entry.where,
-				`"${entry.name}" is not a valid MCP tool name`,
-				"use lowercase letters, digits, dashes and underscores",
-			);
-		}
-		const previous = seen.get(entry.name);
-		if (previous) {
-			report.error(
-				entry.where,
-				`name "${entry.name}" is already taken by ${previous.kind} ${previous.where}`,
-				"tool and widget names share one namespace — rename one of them",
-			);
-		}
-		seen.set(entry.name, entry);
-	}
-
-	// An endpoint's file position is its URL, so a segment that cannot appear in
-	// a URL is a file served somewhere unguessable, and two files resolving to
-	// one path means the second mount is dead — Express answers from the first.
-	const paths = new Map();
-	// The generator names one import per endpoint, camel-cased from the path, so
-	// two paths that camel-case alike (`api/cal-slots.ts`, `api/cal/slots.ts`)
-	// would emit the same identifier twice and fail in generated code the author
-	// cannot open.
-	const identifiers = new Map();
-	for (const endpoint of app.endpoints) {
-		const where = rel(root, endpoint.file);
-
-		const identifier = endpoint.segments.join("-").replace(/[^a-zA-Z0-9]/g, "").toLowerCase();
-		const clash = identifiers.get(identifier);
-		if (clash) {
-			report.error(
-				where,
-				`this path generates the same import name as ${clash}`,
-				"rename one of the two — the generator derives an identifier from the path",
-			);
-		}
-		identifiers.set(identifier, where);
-
-		for (const segment of endpoint.segments) {
-			if (SEGMENT_RE.test(segment)) continue;
-			report.error(
-				where,
-				`"${segment}" cannot be part of a URL path`,
-				"use letters, digits, dashes, dots and underscores — the file's position is the endpoint's path",
-			);
-		}
-
-		const previous = paths.get(endpoint.path);
-		if (previous) {
-			report.error(
-				where,
-				`${endpoint.path} is already served by ${previous}`,
-				"two files resolve to one path — Express answers from the first, so this one never runs",
-			);
-		}
-		paths.set(endpoint.path, where);
-	}
-
-	// Flows point at widgets by name. Catching a typo here beats catching it
-	// when a user is halfway through a conversation.
-	const widgetNames = new Set(app.widgets.map((w) => w.name));
-	for (const flow of app.flows) {
-		const source = readFileSync(flow.file, "utf-8");
-		for (const match of source.matchAll(/showWidget\(\s*\{[^}]*?tool:\s*["'`]([^"'`]+)["'`]/gs)) {
-			const target = match[1];
-			if (!widgetNames.has(target)) {
-				report.error(
-					rel(root, flow.file),
-					`showWidget references the widget "${target}", which does not exist`,
-					widgetNames.size > 0
-						? `known widgets: ${[...widgetNames].join(", ")}`
-						: "this app has no widgets/ folder",
-				);
-			}
-		}
-	}
-}
-
-/** Import each module and check the shape of what it exports. */
-async function checkModules(app, report) {
-	const { root } = app;
-
-	if (app.configFile) {
-		const config = await load(app.configFile, rel(root, app.configFile), report);
-		if (config && !config.name) {
-			report.error(
-				rel(root, app.configFile),
-				"defineApp() is missing `name`",
-				"the MCP server name, e.g. name: 'oney-split-payment'",
-			);
-		}
-	}
-
-	for (const tool of app.tools) {
-		const where = rel(root, tool.file);
-		const def = await load(tool.file, where, report);
-		if (!def) continue;
-		if (typeof def.run !== "function") {
-			report.error(where, "tool is missing run()", "export default defineTool({ ..., run })");
-		}
-		if (!def.description) {
-			report.error(
-				where,
-				"tool is missing a description",
-				"the description is how the model decides to call it — say when to use it",
-			);
-		}
-		if (!def.title) {
-			report.warn(where, "tool is missing a title", "titles show up in connector UIs");
-		}
-	}
-
-	for (const widget of app.widgets) {
-		if (!widget.contract) continue;
-		const where = rel(root, widget.contract);
-		const def = await load(widget.contract, where, report);
-		if (!def) continue;
-		if (!def.data || typeof def.data !== "object") {
-			report.error(
-				where,
-				"widget is missing a `data` schema",
-				"data is the single schema for input, output, and the component's props",
-			);
-		}
-		if (!def.description) {
-			report.error(
-				where,
-				"widget is missing a description",
-				"the description is how the model decides to show it",
-			);
-		}
-	}
-
-	for (const endpoint of app.endpoints) {
-		const where = rel(root, endpoint.file);
-		const def = await load(endpoint.file, where, report);
-		if (!def) continue;
-		if (typeof def.handler !== "function") {
-			report.error(
-				where,
-				"endpoint is missing handler()",
-				"export default defineEndpoint({ handler: (req, res) => { ... } })",
-			);
-		}
-		for (const method of def.method ? [def.method].flat() : []) {
-			if (HTTP_METHODS.has(method)) continue;
-			report.error(
-				where,
-				`"${method}" is not an HTTP method`,
-				`one of: ${[...HTTP_METHODS].join(", ")}`,
-			);
-		}
-	}
-
-	for (const flow of app.flows) {
-		const where = rel(root, flow.file);
-		const def = await load(flow.file, where, report);
-		if (!def) continue;
-		if (!def.name || !def.config || typeof def.handler !== "function") {
-			report.error(
-				where,
-				"this is not a compiled flow",
-				"export default createFlow({ ... }).addEdge(...).compile()",
-			);
-		}
-	}
-}
-
-/**
- * App modules are TypeScript, and they import each other with the `.js`
- * specifiers TypeScript's ESM output requires — `../lib/plans.js` for a file on
- * disk called `plans.ts`. Node's built-in type stripping does not remap those,
- * so validation registers tsx's resolver before importing anything out of the
- * app folder. Bun does the remapping on its own, which is what hid this while
- * the CLI still ran under bun.
- *
- * Registration is global to the process and idempotent here, so it happens once
- * on the first load rather than at startup — `waniwani start` never validates.
- */
-let resolverRegistered = false;
-async function registerTypeScriptResolver() {
-	if (resolverRegistered) return;
-	resolverRegistered = true;
-	const { register } = await import("tsx/esm/api");
-	register();
-}
-
-async function load(file, where, report) {
-	try {
-		await registerTypeScriptResolver();
-		const module = await import(`${file}?t=${Date.now()}`);
-		const def = module.default;
-		if (!def) {
-			report.error(where, "no default export", "the runtime loads this module's default export");
-			return null;
-		}
-		return def;
-	} catch (error) {
-		report.error(where, "failed to load", error instanceof Error ? error.message : String(error));
-		return null;
-	}
-}
-
-/**
- * The SDK version an app asked for, against the floor this package declares.
- *
- * `@waniwani/sdk` is a required peer (see the manifest's `//sdk` note), so the
- * app owns the version and this is the one place that says what the runtime and
- * the pinned template need underneath it. It reads two manifests off disk and
- * fetches nothing, which is why it runs in `check` rather than waiting for the
- * dependency merge in `codegen.mjs` — a version that cannot work should not
- * need a template download to be told so.
- *
- * Undeclared is not an error. npm and bun both install a required peer, and
- * `codegen.mjs` writes one into the generated project, so an app that never
- * mentions the SDK still gets a working copy.
- */
-function checkPeers(app, report) {
-	let manifest;
-	try {
-		manifest = JSON.parse(readFileSync(join(app.root, "package.json"), "utf-8"));
-	} catch {
-		// No manifest, or an unparseable one. Both are `init`'s business, and
-		// neither is improved by a second error about a dependency inside it.
-		return;
-	}
-
-	const name = "@waniwani/sdk";
-	const spec = manifest.dependencies?.[name] ?? manifest.devDependencies?.[name];
-	if (spec == null) {
-		return;
-	}
-
-	const floor = floorOf(name);
-	const suggestion = installable(name);
-	switch (compare(spec, name)) {
-		case "below":
-			report.error(
-				"package.json",
-				`${name} ${spec} cannot reach ${floor}, which this kit needs`,
-				`no version that range allows will work: below the floor the SDK declares a @modelcontextprotocol/ext-apps peer that conflicts with the framework's, and npm refuses the tree. Set ${name} to ${suggestion}.`,
-			);
-			break;
-		case "prerelease":
-			report.warn(
-				"package.json",
-				`${name} ${spec} is a prerelease, and ${floor} does not accept one`,
-				`npm and bun both exclude a prerelease from a range that names none, so the install warns and the tree may not be what this spec says. Deliberate is fine; ${suggestion} is the released floor.`,
-			);
-			break;
-		case "reachable":
-			report.warn(
-				"package.json",
-				`${name} ${spec} also allows versions below ${floor}`,
-				`a fresh install resolves above the floor, and a lockfile written before it moved can hold this tree below it. ${suggestion} says the floor out loud.`,
-			);
-			break;
-		default:
-			// "ok", and "unknown" for an expression this cannot parse — a
-			// workspace protocol or a git URL, where the version is not in the
-			// string and guessing at it would be a false alarm either way.
-			break;
-	}
-}
-
-export async function validateApp(app) {
-	// The check imports every server-safe module for real, and a module that
-	// builds a client at import time reads the environment while doing it. An app
-	// that runs fine would otherwise fail its own build check over a variable
-	// sitting in the file next to it.
-	loadAppEnv(app.root);
-	const report = new Report(app.root);
-	checkStructure(app, report);
-	checkPeers(app, report);
-	// Importing broken modules produces noise on top of structural errors.
-	if (report.ok) {
-		await checkModules(app, report);
-	}
-	return report;
-}