@waniwani/kit 0.1.6-beta.0 → 0.1.6

package/cli/codegen.mjs

@@ -41,6 +41,7 @@ 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");
@@ -196,10 +197,6 @@ const PINS = {
 			version: declared("skybridge"),
 			why: "the template's range floats within 1.x; the runtime is built and verified against this one",
 		},
-		"@waniwani/sdk": {
-			version: declared("@waniwani/sdk"),
-			why: "flows and tracking need the current SDK",
-		},
 	},
 	devDependencies: {
 		"@skybridge/devtools": {
@@ -209,6 +206,34 @@ const PINS = {
 	},
 };
 
+/**
+ * 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",
+		},
+	},
+};
+
 /** Added only when absent, so a template that declares a newer one keeps it. */
 const ENSURED = {
 	dependencies: {},
@@ -861,6 +886,22 @@ function generatePackageJson(app, appPackageJson, template, layout) {
 			}
 		}
 
+		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;
 	};
 
@@ -1164,17 +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 forced
-				// while doing it. 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.
+				// 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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waniwani/kit",
-  "version": "0.1.6-beta.0",
+  "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,10 +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.",
-  "//skybridge": "skybridge and @skybridge/devtools are exact, and the two versions match each other. codegen.mjs forces both on every generated app by reading them back out of this file, so a range here would mean the kit was verified against whatever it resolved while apps were pinned to something else. Bumping them is scripts/bump-deps.mjs, and scripts/template-contract.mjs is what proves the bump.",
   "files": [
     "dist",
     "src",
@@ -49,7 +45,6 @@
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.3",
-    "@waniwani/sdk": "0.19.9-beta.0",
     "cors": "^2.8.6",
     "dotenv": "^17.4.1",
     "express": "^5.2.1",
@@ -63,6 +58,7 @@
     "@skybridge/devtools": "1.4.0"
   },
   "peerDependencies": {
+    "@waniwani/sdk": ">=0.19.9-beta.0",
     "react": ">=19",
     "react-dom": ">=19",
     "zod": "^4"