@waniwani/kit 0.1.5 → 0.1.6

package/cli/codegen.mjs

@@ -41,12 +41,38 @@ import {
 } from "node:fs";
 import { basename, dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
+import { compare, floorOf, installable } from "./peers.mjs";
 
 const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 const RUNTIME_SRC = join(PACKAGE_ROOT, "src");
-const PACKAGE_VERSION = JSON.parse(
-	readFileSync(join(PACKAGE_ROOT, "package.json"), "utf-8"),
-).version;
+/** This package's own manifest, which is where every version below comes from. */
+const MANIFEST = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf-8"));
+const PACKAGE_VERSION = MANIFEST.version;
+
+/**
+ * A version this package declares, read back out so it is stated once.
+ *
+ * Every version the generator forces on an app is a version the generator was
+ * built and verified against, which makes this manifest the only honest source
+ * for it. Writing the same range a second time as a literal down in `PINS` gave
+ * one fact two homes, and a bump could update either one alone: the manifest
+ * carried `skybridge@^1.3.5` while the pin forced `1.4.0`, and they agreed only
+ * because that is what the lockfile happened to resolve.
+ *
+ * Missing throws rather than defaults. `undefined` here would land in a
+ * generated `package.json` as a dependency with no version and fail at install
+ * time in someone else's project, a long way from the rename that caused it.
+ */
+function declared(name, field = "dependencies") {
+	const version = MANIFEST[field]?.[name];
+	if (!version) {
+		throw new Error(
+			`@waniwani/kit declares no ${field}.${name}, and the generator pins apps to it — ` +
+				"add it back to packages/kit/package.json or drop it from PINS",
+		);
+	}
+	return version;
+}
 
 /**
  * The template comes across whole, minus an explicit list.
@@ -160,17 +186,51 @@ const SEAM = { file: "src/server.ts", symbol: "registerApp" };
  *
  * Each entry carries its reason, and the CLI reports what it changed.
  */
-/** Forced to an exact version: the generated code is built against these. */
+/**
+ * Forced to what this package declares: the generated code is built against
+ * these, and `declared()` is what keeps the two statements of that one fact
+ * from drifting apart.
+ */
 const PINS = {
 	dependencies: {
 		skybridge: {
-			version: "1.4.0",
+			version: declared("skybridge"),
 			why: "the template's range floats within 1.x; the runtime is built and verified against this one",
 		},
-		"@waniwani/sdk": { version: "^0.19.5", why: "flows and tracking need the current SDK" },
 	},
 	devDependencies: {
-		"@skybridge/devtools": { version: "1.4.0", why: "must match the framework" },
+		"@skybridge/devtools": {
+			version: declared("@skybridge/devtools", "devDependencies"),
+			why: "must match the framework",
+		},
+	},
+};
+
+/**
+ * Peer floors, checked against what the merge produced rather than forced over
+ * it.
+ *
+ * `@waniwani/sdk` was a `PINS` entry, which made this generator the authority
+ * on an app's SDK version. It was the wrong authority twice over: nothing under
+ * `src/` imports the SDK, so the version was never verified against anything
+ * here, and an app that disagreed kept its own choice and ended up with two
+ * copies in the tree — `createFlow()` compiling against the app's while this
+ * runtime registered the result against the kit's. It is a required peer now
+ * (see the manifest's `//sdk` note), so the app or the template names the
+ * version and this states the floor underneath both.
+ *
+ * Absent is filled in, and below the floor is reported. Nothing is forced
+ * upward: an app on a newer SDK than the template asked for is an app that
+ * upgraded, and overwriting that is how the second copy got there in the first
+ * place. The floor an app can act on is checked earlier and without a template
+ * download, in `checkPeers` in `./validate.mjs`; this covers the version a
+ * template contributed, which that check cannot see.
+ */
+const FLOORS = {
+	dependencies: {
+		"@waniwani/sdk": {
+			why: "below this, npm will not install the SDK next to skybridge 1.4.0 — see the manifest's //sdk note",
+		},
 	},
 };
 
@@ -186,6 +246,36 @@ const ENSURED = {
 	},
 };
 
+/**
+ * What the vendored runtime needs declared, for the eject layout only.
+ *
+ * A build reaches the runtime through `@waniwani/kit`, so express, cors and
+ * their types arrive as that package's own dependencies — which is why it
+ * declares them (see its `//dependencies` and `//express` notes). Ejecting drops
+ * the package and copies `src/` in as source, and the imports come with it: the
+ * vendored tree imports `express` and `cors` by name, and `tsc` needs their
+ * types. Nothing was putting either back, so an ejected project installed and
+ * then failed to compile on ten TS7006/TS7016 errors, with express and cors
+ * present in `node_modules` only as a transitive hoist out of the framework.
+ *
+ * Only the two the runtime imports and the app does not already get: `skybridge`
+ * and `zod` are the other bare specifiers under `src/`, and both are declared
+ * for every layout already.
+ */
+const VENDORED = {
+	dependencies: {
+		express: { version: declared("express"), why: "the vendored runtime imports express" },
+		cors: { version: declared("cors"), why: "the vendored runtime mounts CORS per endpoint" },
+	},
+	devDependencies: {
+		"@types/express": {
+			version: declared("@types/express"),
+			why: "the vendored runtime is typed against express",
+		},
+		"@types/cors": { version: declared("@types/cors"), why: "same, for cors" },
+	},
+};
+
 /**
  * Scripts the generated layout needs, added only when the template has no
  * script by that name. The template's own scripts are left untouched.
@@ -625,6 +715,13 @@ export const app = {
 	title: config.title,
 	version: config.version ?? ${JSON.stringify(version ?? "0.0.0")},
 	instructions: config.instructions,
+	// Forwarded whole, for the template to read if it has anything to read them
+	// with: \`search\` tunes the search tool a template ships, \`tracking\` reaches
+	// the SDK's withWaniwani(). A template that uses neither ignores both, so
+	// emitting them unconditionally keeps one generator working across templates
+	// that read them and templates that do not.
+	search: config.search,
+	tracking: config.tracking,
 };
 
 export async function registerApp(server: McpServer): Promise<void> {
@@ -779,6 +876,32 @@ function generatePackageJson(app, appPackageJson, template, layout) {
 			overrides.push({ name, to: version, why });
 		}
 
+		// Same rule as ENSURED — an app or template declaring its own keeps it —
+		// but only where the runtime arrives as source rather than as a package.
+		if (layout.vendored) {
+			for (const [name, { version, why }] of Object.entries(VENDORED[kind] ?? {})) {
+				if (merged[name]) continue;
+				merged[name] = version;
+				overrides.push({ name, to: version, why });
+			}
+		}
+
+		for (const [name, { why }] of Object.entries(FLOORS[kind] ?? {})) {
+			if (!merged[name]) {
+				merged[name] = installable(name);
+				overrides.push({ name, to: merged[name], why });
+				continue;
+			}
+			if (compare(merged[name], name) === "below") {
+				overrides.push({
+					name,
+					to: merged[name],
+					why: `below ${floorOf(name)}, which this kit needs: ${why}`,
+					conflict: true,
+				});
+			}
+		}
+
 		return merged;
 	};
 
@@ -1082,6 +1205,28 @@ export function generate(app, { template, layout: layoutName = "build", outDir }
 				sha: template.sha,
 				local: template.local,
 				manifest: manifest ? MANIFEST_FILE : undefined,
+				// Which generator wrote this tree, and the versions it was built
+				// against. A deployed app misbehaving is the case this serves:
+				// the tree itself then answers which template commit and which
+				// SDK it was built from, without a guess from the app's lockfile
+				// or from whatever the CLI happens to pin today.
+				//
+				// Two fields because there are two kinds of answer. `pins` is
+				// what this generator forced, and `peers` is what the app or the
+				// template chose while this generator only stated a floor — the
+				// SDK moved from the first to the second when it became a peer,
+				// and it is the one most worth reading back.
+				kit: PACKAGE_VERSION,
+				pins: Object.fromEntries(
+					Object.values(PINS).flatMap((group) =>
+						Object.entries(group).map(([name, pin]) => [name, pin.version]),
+					),
+				),
+				peers: Object.fromEntries(
+					Object.entries(FLOORS).flatMap(([kind, group]) =>
+						Object.keys(group).map((name) => [name, packageJson[kind]?.[name]]),
+					),
+				),
 				// What survived to the end, copied and generated alike. The
 				// copy is the raw list minus whatever a generated file replaced,
 				// and the generated half is here so that a build which stops

package/cli/init.mjs

@@ -33,6 +33,7 @@ import { basename, dirname, join, relative } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 import { bold, dim, green, red, yellow } from "./log.mjs";
+import { installable } from "./peers.mjs";
 
 const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 const MANIFEST = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf-8"));
@@ -65,36 +66,28 @@ function cleanTitle(input) {
 		.trim();
 }
 
-/**
- * A peer range is a floor, `>=19`, and a floor in an app's dependencies installs
- * the next major on the day it lands. Cap it. Anything already ranged, `^4`,
- * passes through as it is.
- */
-function installable(name, range) {
-	if (!range) {
-		throw new Error(`@waniwani/kit declares no peer range for ${name}: this package's manifest moved`);
-	}
-	const floor = /^>=\s*(\d+)(?:\.(\d+))?(?:\.(\d+))?$/.exec(range.trim());
-	return floor ? `^${floor[1]}.${floor[2] ?? 0}.${floor[3] ?? 0}` : range;
-}
-
 /**
  * What a new app depends on.
  *
  * Every version is read off this package's own manifest: `@waniwani/kit` at the
- * version of the CLI doing the scaffolding, `@waniwani/sdk` at the version this
- * runtime is built against, and react, react-dom and zod at the peer ranges this
- * package declares. A scaffold that wrote its own numbers here would be the one
- * file in the folder that can be wrong the day it is created.
+ * version of the CLI doing the scaffolding, and the four peers at the floors
+ * this package declares, capped by `installable` so a floor does not install
+ * the next major on the day it lands. A scaffold that wrote its own numbers
+ * here would be the one file in the folder that can be wrong the day it is
+ * created.
+ *
+ * `@waniwani/sdk` is written out even though a required peer is auto-installed
+ * without it, because the app imports it directly — `flows/*.ts` calls
+ * `createFlow` — and a package you import belongs in your own manifest rather
+ * than arriving because something else asked for it.
  */
 function dependencies() {
-	const peers = MANIFEST.peerDependencies ?? {};
 	return {
 		"@waniwani/kit": `^${MANIFEST.version}`,
-		"@waniwani/sdk": MANIFEST.dependencies["@waniwani/sdk"],
-		react: installable("react", peers.react),
-		"react-dom": installable("react-dom", peers["react-dom"]),
-		zod: installable("zod", peers.zod),
+		"@waniwani/sdk": installable("@waniwani/sdk"),
+		react: installable("react"),
+		"react-dom": installable("react-dom"),
+		zod: installable("zod"),
 	};
 }
 

package/cli/peers.mjs

@@ -0,0 +1,170 @@
+/**
+ * The peer ranges this package declares, and what to do with them.
+ *
+ * `@waniwani/sdk`, react, react-dom and zod reach an app as peers rather than
+ * as this package's own dependencies, so the app holds one copy and this
+ * package states only the floor underneath it. Three callers need that floor
+ * and each needs it differently: `init.mjs` writes an installable range into a
+ * new app, `validate.mjs` checks the range an existing app already wrote, and
+ * `codegen.mjs` fills one in when neither the app nor the template declared
+ * one. One module so the parsing exists once.
+ *
+ * Deliberately not a semver dependency. What appears in a real app's manifest
+ * is an exact version, a caret, a tilde or a `>=` floor, and comparing those
+ * against a floor is the whole job. Anything this cannot parse is reported as
+ * unknown rather than guessed at — see `compare`.
+ */
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const MANIFEST = JSON.parse(
+	readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf-8"),
+);
+
+/**
+ * A peer range this package declares, read back out so it is stated once.
+ *
+ * Missing throws. A floor that silently defaulted would let every check below
+ * pass vacuously, which is worse than the rename that removed it.
+ */
+export function peerRange(name) {
+	const range = MANIFEST.peerDependencies?.[name];
+	if (!range) {
+		throw new Error(
+			`@waniwani/kit declares no peerDependencies.${name}, and its own tooling reads that floor — ` +
+				"add it back to packages/kit/package.json, or drop the entry that reads it",
+		);
+	}
+	return range;
+}
+
+/**
+ * A peer range turned into something an app can depend on.
+ *
+ * A peer range is a floor, `>=19`, and a floor in an app's dependencies
+ * installs the next major on the day it lands. Cap it. Anything already ranged,
+ * `^4`, passes through as it is.
+ *
+ * The prerelease tail is part of the pattern because a floor can carry one, and
+ * `>=0.19.9-beta.0` falling through uncapped would put the very floor this
+ * exists to cap into a new app's manifest. `^0.19.9-beta.0` keeps the
+ * prerelease reachable and still stops at `0.20.0`.
+ */
+export function installable(name) {
+	const range = peerRange(name);
+	const floor = /^>=\s*(\d+)(?:\.(\d+))?(?:\.(\d+))?(-[0-9A-Za-z.-]+)?$/.exec(range.trim());
+	return floor ? `^${floor[1]}.${floor[2] ?? 0}.${floor[3] ?? 0}${floor[4] ?? ""}` : range;
+}
+
+/** `1.2.3-beta.0` → `{ parts: [1,2,3], prerelease: "beta.0" }` */
+function parseVersion(input) {
+	const match = /^(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-([0-9A-Za-z.-]+))?$/.exec(input.trim());
+	if (!match) return null;
+	return {
+		parts: [Number(match[1]), Number(match[2] ?? 0), Number(match[3] ?? 0)],
+		prerelease: match[4],
+	};
+}
+
+/** Ordering on major.minor.patch, with a prerelease sorting below its release. */
+function order(a, b) {
+	for (let i = 0; i < 3; i++) {
+		if (a.parts[i] !== b.parts[i]) return a.parts[i] < b.parts[i] ? -1 : 1;
+	}
+	if (a.prerelease && !b.prerelease) return -1;
+	if (!a.prerelease && b.prerelease) return 1;
+	return 0;
+}
+
+/**
+ * The window a dependency spec opens, as `{ low, high }`, where `high` is
+ * exclusive and `null` means unbounded.
+ *
+ * Caret follows semver's 0.x rule, which is the one that matters for the SDK:
+ * `^0.19.5` stops at `0.20.0`, so an SDK minor is a breaking change.
+ */
+function window(spec) {
+	const trimmed = spec.trim();
+	if (trimmed === "*" || trimmed === "" || trimmed === "latest") {
+		return { low: parseVersion("0.0.0"), high: null };
+	}
+
+	const ranged = /^(\^|~|>=)\s*(.+)$/.exec(trimmed);
+	if (!ranged) {
+		const exact = parseVersion(trimmed.replace(/^=\s*/, ""));
+		return exact ? { low: exact, high: exact, exact: true } : null;
+	}
+
+	const low = parseVersion(ranged[2]);
+	if (!low) return null;
+	if (ranged[1] === ">=") return { low, high: null };
+
+	const [major, minor] = low.parts;
+	// `~1.2.3` caps at the next minor. `^1.2.3` caps at the next major, except
+	// under 0.x where the minor is the compatibility boundary.
+	const high =
+		ranged[1] === "~" || major === 0
+			? { parts: [major, minor + 1, 0], prerelease: undefined }
+			: { parts: [major + 1, 0, 0], prerelease: undefined };
+	return { low, high };
+}
+
+/**
+ * How a dependency spec sits against a peer floor.
+ *
+ * - `"ok"` — every version the spec allows is at or above the floor.
+ * - `"reachable"` — the spec allows the floor, and also allows something below
+ *   it. A fresh install lands above the floor and a lockfile written earlier
+ *   can hold the tree below it, so this is a warning rather than an error.
+ * - `"below"` — no version the spec allows reaches the floor. This one cannot
+ *   resolve to a working tree.
+ * - `"prerelease"` — a prerelease, at or above the floor by number, which npm's
+ *   semver rules still exclude from a range carrying no prerelease of its own.
+ *   Both npm and bun warn on it, so reporting it as `ok` would have this check
+ *   disagreeing with the tool that actually resolves the tree.
+ * - `"unknown"` — an expression this module does not parse (a union, a git
+ *   URL, `workspace:*`). Reported as-is rather than assumed to be either.
+ */
+export function compare(spec, name) {
+	const range = peerRange(name);
+	const floorMatch = /^>=\s*(.+)$/.exec(range.trim());
+	const floor = parseVersion(floorMatch ? floorMatch[1] : range.replace(/^[\^~=]\s*/, ""));
+	const allowed = spec == null ? null : window(spec);
+	if (!floor || !allowed) return "unknown";
+
+	// A prerelease is opt-in under semver: `0.19.9-beta.0` does not satisfy
+	// `>=0.19.8`, because the range names no prerelease at that version. The
+	// floor carrying one of its own is someone pinning a prerelease on purpose,
+	// and then the plain comparison is what they asked for.
+	if (allowed.low.prerelease && !floor.prerelease) return "prerelease";
+	if (order(allowed.low, floor) >= 0) return "ok";
+	if (allowed.high === null || order(allowed.high, floor) > 0) return "reachable";
+	return "below";
+}
+
+/** The floor itself, for a message that has to name it. */
+export function floorOf(name) {
+	return peerRange(name);
+}
+
+/**
+ * The lowest version a spec allows, normalised, or null if unparseable.
+ *
+ * `scripts/bump-deps.mjs` asks the question this answers, and it is the mirror
+ * of `compare`: that one checks a spec against this package's floor, while a
+ * floor bump needs to know whether the *template's* floor has risen above it.
+ */
+export function floorVersion(spec) {
+	const allowed = spec == null ? null : window(spec);
+	return allowed?.low ? allowed.low.parts.join(".") : null;
+}
+
+/** Ordering on two version strings, for a caller with no window to compare. */
+export function compareVersions(a, b) {
+	const left = parseVersion(a);
+	const right = parseVersion(b);
+	if (!left || !right) return null;
+	return order(left, right);
+}

package/cli/template.mjs

@@ -19,13 +19,35 @@ 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).
+ * 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#beta";
+export const DEFAULT_TEMPLATE =
+	"github:WaniWani-AI/mcp-distribution-template#c0d00e72a3733a5f42389731fe6bbaf7e0e07863";
 
 const CACHE_ROOT = join(homedir(), ".cache", "waniwani", "templates");
 
@@ -36,11 +58,21 @@ function parseGithub(source) {
 	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}`, {
@@ -148,5 +180,11 @@ export async function resolveTemplate(source = DEFAULT_TEMPLATE) {
 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})`;
+	// 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

@@ -7,8 +7,9 @@
  */
 
 import { readFileSync } from "node:fs";
-import { relative } from "node:path";
+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])?$/;
 
@@ -311,6 +312,68 @@ async function load(file, where, report) {
 	}
 }
 
+/**
+ * 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
@@ -319,6 +382,7 @@ export async function validateApp(app) {
 	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);

package/dist/index.d.ts

@@ -35,6 +35,100 @@ export type ToolHints = {
     /** Calling twice with the same input has the same effect as calling once. */
     idempotent?: boolean;
 };
+/**
+ * What an app may set on the template's `search` tool.
+ *
+ * Declared here and again in the template's `src/search/index.ts`, on purpose:
+ * the template does not depend on this package, so there is no type to share.
+ * The two meet at the generated `waniwani.ts` and nowhere else, which makes this
+ * a mirror that has to be kept in step by hand. A field added on one side and
+ * not the other is silently dropped rather than reported.
+ */
+export type SearchOptions = {
+    /**
+     * Whether the template registers the tool at all.
+     *
+     * `false` is the only way an app can decline it, because it cannot unregister
+     * what the template has already registered. Worth using: a deployment with no
+     * corpus behind it, or one holding another market's documents, is better off
+     * without the tool than with one answering confidently out of the wrong file.
+     */
+    enabled?: boolean;
+    /** Passages to ask for, 1-20. Unset leaves the SDK's default of 5. */
+    topK?: number;
+    /**
+     * Similarity floor, 0-1, under which a passage is dropped rather than ranked
+     * last. Unset leaves the SDK's default of 0.3.
+     */
+    minScore?: number;
+    /**
+     * Exact-match filter on chunk metadata: a passage must carry all of these
+     * pairs to come back. With the corpus tagged at ingest time, this is a gate in
+     * code rather than a line of prompt.
+     */
+    metadata?: Record<string, string>;
+    /** Give up on a slow search and answer as though nothing matched. */
+    timeoutMs?: number;
+    /** Name the source document on each passage. */
+    includeSources?: boolean;
+    /**
+     * Framing prepended to the answer text. Retrieved passages are third-party
+     * text on its way into a prompt; this is where an app says they are reference
+     * material rather than instructions.
+     */
+    preamble?: string;
+    /**
+     * Status text the host shows while the call is in flight, and once it has
+     * returned. Configurable because the defaults are English and this string is
+     * one of the few a user actually reads.
+     */
+    invoking?: string;
+    invoked?: string;
+};
+/** The event categories the tracking backend recognises. */
+export type ToolType = "pricing" | "product_info" | "availability" | "support" | "other";
+/**
+ * Tracking options, forwarded whole to the SDK's `withWaniwani()`.
+ *
+ * A mirror of that function's options for the same reason as `SearchOptions`
+ * above, narrowed to what an app declares rather than constructs: the SDK also
+ * accepts a `client` instance and an `onError` callback, and neither belongs in a
+ * config file.
+ *
+ * `flushAfterToolCall` is the one that matters on serverless. An invocation
+ * frozen between tool calls takes any unsent event batch with it, and this is
+ * the only way an app can ask for the flush.
+ */
+export type TrackingOptions = {
+    /** One category for every tool, or a function mapping tool name to category. */
+    toolType?: ToolType | ((toolName: string) => ToolType | undefined);
+    /** Merged into every tracked event. */
+    metadata?: Record<string, unknown>;
+    /** Flush the tracking transport after each tool call. */
+    flushAfterToolCall?: boolean;
+    /**
+     * Put widget tracking config in each tool response's `_meta.waniwani`, so a
+     * widget in the browser can send its own events.
+     *
+     * @default true
+     */
+    injectWidgetToken?: boolean;
+    /**
+     * Field names to strip from location `_meta` before events are sent. Pass
+     * `["latitude", "longitude"]` to drop coordinates and keep the rest.
+     *
+     * @default []
+     */
+    stripLocationFields?: readonly string[];
+    /**
+     * Replace flow state fields marked with `redacted()` before they are tracked.
+     * Wire it to an env var to keep real values in development and redact in
+     * production.
+     *
+     * @default false
+     */
+    applyFieldRedactions?: boolean;
+};
 export type AppConfig = {
     /** MCP server name, e.g. `oney-split-payment`. */
     name: string;
@@ -47,6 +141,14 @@ export type AppConfig = {
      * call. Tone, guardrails, what this app is for.
      */
     instructions?: string;
+    /**
+     * Tune, or decline, the `search` tool the template ships. Reaches the
+     * template through the generated `waniwani.ts`; a template that ships no such
+     * tool ignores it.
+     */
+    search?: SearchOptions;
+    /** Tracking behaviour for every tool call this app serves. */
+    tracking?: TrackingOptions;
 };
 export declare function defineApp(config: AppConfig): AppConfig;
 /**

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AA2CH,MAAM,UAAU,SAAS,CAAC,MAAiB;IAC1C,OAAO,MAAM,CAAC;AACf,CAAC;AAwBD,MAAM,UAAU,UAAU,CACzB,GAAyB;IAEzB,OAAO,GAAG,CAAC;AACZ,CAAC;AAuCD,MAAM,UAAU,YAAY,CAAkB,GAAwB;IACrE,OAAO,GAAG,CAAC;AACZ,CAAC;AA4CD,MAAM,UAAU,cAAc,CAAC,GAAuB;IACrD,OAAO,GAAG,CAAC;AACZ,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAoJH,MAAM,UAAU,SAAS,CAAC,MAAiB;IAC1C,OAAO,MAAM,CAAC;AACf,CAAC;AAwBD,MAAM,UAAU,UAAU,CACzB,GAAyB;IAEzB,OAAO,GAAG,CAAC;AACZ,CAAC;AAuCD,MAAM,UAAU,YAAY,CAAkB,GAAwB;IACrE,OAAO,GAAG,CAAC;AACZ,CAAC;AA4CD,MAAM,UAAU,cAAc,CAAC,GAAuB;IACrD,OAAO,GAAG,CAAC;AACZ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waniwani/kit",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Build an MCP app as a folder: tools, widgets and flows, with one CLI and one shared server runtime.",
   "type": "module",
   "bin": {
@@ -22,9 +22,6 @@
       "default": "./dist/web.js"
     }
   },
-  "//files": "`src` ships alongside `dist` on purpose: `waniwani eject` vendors the runtime as readable TypeScript, and it reads it out of the installed package.",
-  "//dependencies": "tsx, typescript and the @types packages are here rather than in devDependencies because the underlying framework shells out to tsc and tsx by bare name and resolves types from the app repo tree, while declaring none of them. An app repo owns no build config, so this package is the only thing that can put them there. nodemon is the fourth of that set and arrives on its own, as a peer of it.",
-  "//express": "express and cors back the api/ convention: the runtime mounts each endpoint with a JSON body parser and CORS, and an app's handlers are typed against express. Both are already skybridge's own dependencies at these ranges, so declaring them here adds no second copy — it stops an app from depending on a transitive hoist.",
   "files": [
     "dist",
     "src",
@@ -48,20 +45,20 @@
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.3",
-    "@waniwani/sdk": "^0.19.5",
     "cors": "^2.8.6",
     "dotenv": "^17.4.1",
     "express": "^5.2.1",
-    "skybridge": "^1.3.5",
+    "skybridge": "1.4.0",
     "tailwindcss": "^4.3.3",
     "tsx": "^4.20.6",
     "typescript": "^6.0.2",
     "vite": "^8.1.5"
   },
   "devDependencies": {
-    "@skybridge/devtools": "^1.2.7"
+    "@skybridge/devtools": "1.4.0"
   },
   "peerDependencies": {
+    "@waniwani/sdk": ">=0.19.9-beta.0",
     "react": ">=19",
     "react-dom": ">=19",
     "zod": "^4"

package/src/index.ts

@@ -42,6 +42,103 @@ export type ToolHints = {
 
 // ---------------------------------------------------------------- app config
 
+/**
+ * What an app may set on the template's `search` tool.
+ *
+ * Declared here and again in the template's `src/search/index.ts`, on purpose:
+ * the template does not depend on this package, so there is no type to share.
+ * The two meet at the generated `waniwani.ts` and nowhere else, which makes this
+ * a mirror that has to be kept in step by hand. A field added on one side and
+ * not the other is silently dropped rather than reported.
+ */
+export type SearchOptions = {
+	/**
+	 * Whether the template registers the tool at all.
+	 *
+	 * `false` is the only way an app can decline it, because it cannot unregister
+	 * what the template has already registered. Worth using: a deployment with no
+	 * corpus behind it, or one holding another market's documents, is better off
+	 * without the tool than with one answering confidently out of the wrong file.
+	 */
+	enabled?: boolean;
+	/** Passages to ask for, 1-20. Unset leaves the SDK's default of 5. */
+	topK?: number;
+	/**
+	 * Similarity floor, 0-1, under which a passage is dropped rather than ranked
+	 * last. Unset leaves the SDK's default of 0.3.
+	 */
+	minScore?: number;
+	/**
+	 * Exact-match filter on chunk metadata: a passage must carry all of these
+	 * pairs to come back. With the corpus tagged at ingest time, this is a gate in
+	 * code rather than a line of prompt.
+	 */
+	metadata?: Record<string, string>;
+	/** Give up on a slow search and answer as though nothing matched. */
+	timeoutMs?: number;
+	/** Name the source document on each passage. */
+	includeSources?: boolean;
+	/**
+	 * Framing prepended to the answer text. Retrieved passages are third-party
+	 * text on its way into a prompt; this is where an app says they are reference
+	 * material rather than instructions.
+	 */
+	preamble?: string;
+	/**
+	 * Status text the host shows while the call is in flight, and once it has
+	 * returned. Configurable because the defaults are English and this string is
+	 * one of the few a user actually reads.
+	 */
+	invoking?: string;
+	invoked?: string;
+};
+
+/** The event categories the tracking backend recognises. */
+export type ToolType = "pricing" | "product_info" | "availability" | "support" | "other";
+
+/**
+ * Tracking options, forwarded whole to the SDK's `withWaniwani()`.
+ *
+ * A mirror of that function's options for the same reason as `SearchOptions`
+ * above, narrowed to what an app declares rather than constructs: the SDK also
+ * accepts a `client` instance and an `onError` callback, and neither belongs in a
+ * config file.
+ *
+ * `flushAfterToolCall` is the one that matters on serverless. An invocation
+ * frozen between tool calls takes any unsent event batch with it, and this is
+ * the only way an app can ask for the flush.
+ */
+export type TrackingOptions = {
+	/** One category for every tool, or a function mapping tool name to category. */
+	toolType?: ToolType | ((toolName: string) => ToolType | undefined);
+	/** Merged into every tracked event. */
+	metadata?: Record<string, unknown>;
+	/** Flush the tracking transport after each tool call. */
+	flushAfterToolCall?: boolean;
+	/**
+	 * Put widget tracking config in each tool response's `_meta.waniwani`, so a
+	 * widget in the browser can send its own events.
+	 *
+	 * @default true
+	 */
+	injectWidgetToken?: boolean;
+	/**
+	 * Field names to strip from location `_meta` before events are sent. Pass
+	 * `["latitude", "longitude"]` to drop coordinates and keep the rest.
+	 *
+	 * @default []
+	 */
+	stripLocationFields?: readonly string[];
+	/**
+	 * Replace flow state fields marked with `redacted()` before they are tracked.
+	 * Wire it to an env var to keep real values in development and redact in
+	 * production.
+	 *
+	 * @default false
+	 */
+	applyFieldRedactions?: boolean;
+};
+
 export type AppConfig = {
 	/** MCP server name, e.g. `oney-split-payment`. */
 	name: string;
@@ -54,6 +151,14 @@ export type AppConfig = {
 	 * call. Tone, guardrails, what this app is for.
 	 */
 	instructions?: string;
+	/**
+	 * Tune, or decline, the `search` tool the template ships. Reaches the
+	 * template through the generated `waniwani.ts`; a template that ships no such
+	 * tool ignores it.
+	 */
+	search?: SearchOptions;
+	/** Tracking behaviour for every tool call this app serves. */
+	tracking?: TrackingOptions;
 };
 
 export function defineApp(config: AppConfig): AppConfig {