@waniwani/kit 0.1.1 → 0.1.4

package/README.md

@@ -1,6 +1,6 @@
 # @waniwani/kit
 
-**Build an MCP app as a folder.** You write tools, widgets, flows and docs into
+**Build an MCP app as a folder.** You write tools, widgets and flows into
 a directory, and one CLI turns that directory into a deployable MCP server. Your
 repo holds none of the plumbing: server bootstrap, transport wiring, build
 configuration.
@@ -15,8 +15,7 @@ oney/                          # what you write
 ├── waniwani.config.ts
 ├── tools/check-eligibility.ts
 ├── widgets/select-plan/{widget.ts,ui.tsx}
-├── flows/split-payment.ts
-└── docs/*.md
+└── flows/split-payment.ts
 
 waniwani build                 # → .waniwani/, an ordinary npm project
 ```
@@ -82,9 +81,25 @@ registers them come from the kit.
 
 ## Quickstart
 
-There is no `waniwani init` yet, so the first files go in by hand.
-[examples/oney](https://github.com/WaniWani-AI/kit/blob/main/examples/oney) is this same app finished, if you would rather
-read it than type it.
+```bash
+npx @waniwani/kit init oney
+cd oney && npm run dev
+```
+
+`init` writes a folder that already answers: an app config, one tool, and the
+widget that displays what the tool returned. It installs, and the dev
+server is one command away. `--minimal` scaffolds the config and the tool alone,
+`--name` sets the MCP server name, and running it inside an existing repo merges
+into that repo's `package.json` and `.gitignore` instead of replacing them.
+
+Where the app lands follows the argument. `init oney` creates `oney/`, `init .`
+uses the current folder, and a bare `init` asks for a name and reads the answer
+as both: a name of its own creates `./<name>/`, while the offered default, your
+current folder's name, scaffolds in place.
+
+The rest of this section is what those files hold, written out by hand.
+[examples/oney](https://github.com/WaniWani-AI/kit/blob/main/examples/oney) is the same app finished, if you would rather read
+it than type it.
 
 ```bash
 mkdir oney && cd oney
@@ -235,9 +250,8 @@ oney/
 │       └── ui.tsx              export default function Component()
 ├── flows/
 │   └── split-payment.ts        export default createFlow(...).compile()   ← SDK
-├── docs/
-│   ├── fees.md                 becomes the `search_docs` tool
-│   └── eligibility.md
+├── api/
+│   └── cal/slots.ts            export default defineEndpoint({ ..., handler })
 └── lib/                        anything else is just modules
 ```
 
@@ -251,7 +265,7 @@ unwired.
 | `tools/<name>.ts` | one MCP tool | `.ts`, `.tsx` and `.mts` are picked up |
 | `widgets/<name>/` | one MCP tool plus a `ui://` resource | needs `widget.ts` and `ui.tsx` |
 | `flows/<name>.ts` | one MCP tool, registered from the SDK unchanged | whatever `.compile()` returns |
-| `docs/*.md` | a single `search_docs` tool over all of them | the first `# heading` becomes the title |
+| `api/<path>.ts` | one HTTP endpoint at `/api/<path>` | for the browser, invisible to the model |
 | anything else | plain modules | the CLI leaves it alone |
 
 The app folder imports `@waniwani/kit`, plus `@waniwani/sdk` when it uses flows,
@@ -316,6 +330,70 @@ export default createFlow({ id: "split_payment", title, description, state })
 `showWidget({ tool: "select-plan" })` names a widget by its folder name, and the
 build check verifies that the folder exists.
 
+### The api/ folder is for the browser
+
+A widget runs in an iframe on another origin, and it can call its own server
+without going through the model at all. Booking a slot, loading a calendar,
+receiving a webhook: `api/` is where those live. The path comes from the file's
+position, the folder name included, so there is nothing to keep in step with the
+`fetch()` on the other side:
+
+```
+api/cal/slots.ts          →  /api/cal/slots
+api/webhooks/stripe.ts    →  /api/webhooks/stripe
+api/cal/index.ts          →  /api/cal
+```
+
+```ts
+// api/cal/slots.ts
+import { defineEndpoint } from "@waniwani/kit";
+import { fetchCalSlots } from "../../lib/cal.js";
+
+export default defineEndpoint({
+  method: "post",
+  handler: async (req, res) => {
+    const { timeZone } = req.body;
+    res.json({ slots: await fetchCalSlots(regionFor(timeZone)) });
+  },
+});
+```
+
+The widget reaches it at the origin the host hands the view, which is the dev
+port locally and the deployed origin inside ChatGPT or Claude:
+
+```tsx
+const apiUrl = (path: string) => `${window.skybridge?.serverUrl ?? ""}${path}`;
+const response = await fetch(apiUrl("/api/cal/slots"), { method: "POST", body });
+```
+
+Four things arrive with every endpoint, so no app writes them:
+
+| | what the runtime does |
+|---|---|
+| **CORS** | on by default, preflight included, advertising the methods `method` declares and no others |
+| **JSON body** | `express.json()`, because the framework installs no parser of its own and `req.body` would be `undefined` |
+| **method guard** | anything outside `method` gets a 405 and an `Allow` header, instead of reaching a handler written for a POST |
+| **errors** | a handler that throws answers JSON with the message, logged as `[waniwani] endpoint "/api/..." failed`, so a `fetch()` waiting on JSON never receives an HTML error page |
+
+`cors: false` and `json: false` opt out of the first two. Leaving `method` off
+accepts every method.
+
+**Reach for a tool instead when the model is the caller.** An endpoint appears in
+no `tools/list`, costs no turn and no tokens, and the model cannot see that it
+happened. That is what suits a calendar the widget paints for itself, and what
+rules it out for anything the model has to reason about or quote back.
+
+Endpoints share the process with `/mcp`, so `lib/` is one set of modules for
+both, and the build check prints what it mounted:
+
+```
+✓ Build check passed — 1 widget, 1 flow, 2 endpoints
+  widget show-book-call
+  flow   demo-qualification
+  api    /api/cal/book
+  api    /api/cal/slots
+```
+
 ### Styling is Tailwind, and only Tailwind
 
 A widget styles itself with utility classes in its `ui.tsx`. There is no
@@ -392,15 +470,16 @@ letting it sit there doing nothing:
 ## Commands
 
 ```bash
+waniwani init [dir] # scaffold an app folder, install, ready to dev
 waniwani check      # validate the folder
 waniwani dev        # generate + dev server + regenerate on change
 waniwani build      # generate + production build
 waniwani start      # run the production build
-waniwani deploy     # generate + vercel deploy
 waniwani eject [--out dir]   # hand the plumbing over and step out
 ```
 
-Every one of them runs the same four stages before doing its own work.
+`init` writes files and stops there. Every other command runs the same four
+stages before doing its own work.
 
 ```mermaid
 flowchart LR
@@ -409,7 +488,7 @@ flowchart LR
         tools["tools/*.ts"]
         widgets["widgets/&lt;name&gt;/<br/>widget.ts + ui.tsx"]
         flows["flows/*.ts"]
-        docs["docs/*.md"]
+        api["api/**/*.ts"]
     end
 
     subgraph tpl["WaniWani-AI/mcp-distribution-template (public, separate repo)"]
@@ -433,7 +512,7 @@ flowchart LR
     app --> scan --> check --> gen --> out
     runtime -.imported by.-> server
     raw -.fetched at a pinned SHA, copied byte for byte.-> deployfiles
-    out --> deploy["dev · build · start<br/>vercel deploy"]
+    out --> deploy["dev · build · start"]
     app -.waniwani eject.-> ejected["a plain repo<br/><i>no CLI, no @waniwani/kit</i>"]
 ```
 
@@ -450,6 +529,28 @@ flowchart LR
 project carrying a `vercel.json`, which is what lets `vercel deploy` inside it
 work with no special support.
 
+### Secrets live in the app's .env
+
+`.env` and `.env.local` sit next to `waniwani.config.ts`, and every command reads
+them before it runs anything. A variable already exported in the shell or set by
+CI wins over both files, and a hosted deploy sets its variables on the platform
+and reads no file at all.
+
+Loading them this early is what lets a module build its client at import time:
+
+```ts
+// lib/waniwani.ts
+export const wani = waniwani({ apiKey: process.env.WANIWANI_API_KEY });
+```
+
+The generated project runs from `.waniwani/`, one level below the file, and a
+module's imports are evaluated before any line of the module that pulled it in,
+so neither `dotenv/config` nor a load inside generated code arrives in time.
+`waniwani check` reads the same files for the same reason: it imports every
+server-safe module for real, and a flow whose store comes from
+`WANIWANI_API_KEY` would otherwise fail its own build check over a variable
+sitting in the file next to it.
+
 ### What the build check catches
 
 Errors that would otherwise surface as a 500 at request time, or as a widget
@@ -513,9 +614,9 @@ under `src/app/`:
 
 ```
 oney/
-├── src/app/{tools,widgets,flows,docs,lib}/   your code, moved
+├── src/app/{tools,widgets,flows,lib}/        your code, moved
 ├── src/_runtime/                             the runtime, vendored as source
-├── src/{server,waniwani,docs}.ts             entry, registration, inlined docs
+├── src/{server,waniwani}.ts                  entry and registration
 ├── src/views/<widget>.tsx                    view entries
 ├── vite.config.ts  vercel.json  alpic.json   bundling and deploy
 ├── Dockerfile  .dockerignore                 container deploy
@@ -545,8 +646,6 @@ What an ejected repo gives up is the generator, and with it:
 - **the build check**, so `showWidget("typo")` becomes a runtime failure again
 - **name-from-filesystem**, so adding a widget means editing `src/waniwani.ts`
   and adding an entry under `src/views/`
-- **docs auto-scan**, since `src/docs.ts` is a snapshot and new `docs/*.md` need
-  hand-wiring
 - **runtime fixes**, since `src/_runtime/` is a fork from the moment it lands
 
 ## Status
@@ -555,12 +654,12 @@ What an ejected repo gives up is the generator, and with it:
 
 - **`@waniwani/cli` owns the `waniwani` bin on npm**, so installing both
   collides.
-- **No `waniwani init`**, so a new app folder starts by hand.
-- **`waniwani deploy` is wired but unrun** against a real Vercel account.
+- **`waniwani init` scaffolds one shape of app**, a tool with the widget that
+  displays it. A flow is not among the files it writes.
+- **Deploying is manual.** `.waniwani/` carries a `vercel.json`, so
+  `vercel deploy` inside it works, but no command wraps that.
 - **`useWidget` does not track yet.** Emitting `widget_render` and click events
   through `useWaniwani` automatically is the next step.
-- **Docs search is a term-match** rather than the hosted KB. Swapping it for
-  `wani.kb.search` when `WANIWANI_API_KEY` is set is a runtime change only.
 
 Template pinning, the CI contract, publishing requirements and the rest of the
 gap list are in [INTERNALS.md](https://github.com/WaniWani-AI/kit/blob/main/INTERNALS.md).

package/cli/codegen.mjs

@@ -201,7 +201,7 @@ const SCRIPT_ADDITIONS = {
  */
 const SCRIPT_REMOVALS = {
 	"kb:ingest": {
-		why: "ingests knowledge-base/, which is the example's; an app's docs are docs/*.md, inlined at build",
+		why: "ingests knowledge-base/, which is the example's; an app has no such folder",
 	},
 };
 
@@ -247,9 +247,7 @@ const NOT_SOURCE = new Set([
 	".skybridge",
 	".vercel",
 	// The repo's own, not the app's. An in-place eject moves what it copies, and
-	// a README that reappears under `src/app/` is a bad surprise. Docs the app
-	// actually serves live in `docs/*.md` and are inlined separately, so nothing
-	// is lost by skipping these at every level.
+	// a README that reappears under `src/app/` is a bad surprise.
 	"README.md",
 	"LICENSE",
 	// Lockfiles describe the repo's install, and the generated package.json is
@@ -268,7 +266,7 @@ const NOT_SOURCE = new Set([
  * tools in it, and reads `src/waniwani.ts` — the one file this generates into
  * the template's tree.
  */
-const GENERATED = ["src/waniwani.ts", "src/docs.ts", "tsconfig.json", ".template.json"];
+const GENERATED = ["src/waniwani.ts", "tsconfig.json", ".template.json"];
 
 /** `select-plan` -> `selectPlan`, for generated identifiers. */
 function camel(name) {
@@ -592,20 +590,22 @@ function templateStyleDomains(template) {
 
 // ------------------------------------------------------------ generated files
 
-function generateServerApp(app, layout, { runtime, styleDomains }) {
+function generateServerApp(app, layout, { runtime, styleDomains, version }) {
 	const from = appFrom(layout);
 
 	const imports = [
 		`import { config as loadEnv } from "dotenv";`,
 		`import type { McpServer } from "skybridge/server";`,
 		`import { registerApp as register } from "${runtime.server}";`,
-		app.docs.length > 0 ? `import { docs } from "./docs.js";` : null,
 		`import config from "${from}/waniwani.config.js";`,
 		...app.tools.map((t) => `import tool_${camel(t.name)} from "${from}/tools/${t.name}.js";`),
 		...app.widgets.map(
 			(w) => `import widget_${camel(w.name)} from "${from}/widgets/${w.name}/widget.js";`,
 		),
 		...app.flows.map((f) => `import flow_${camel(f.name)} from "${from}/flows/${f.name}.js";`),
+		...app.endpoints.map(
+			(e) => `import endpoint_${camel(e.segments.join("-"))} from "${from}/api/${e.segments.join("/")}.js";`,
+		),
 	].filter(Boolean);
 
 	const list = (items) => (items.length === 0 ? "[]" : `[\n\t\t${items.join(",\n\t\t")},\n\t]`);
@@ -618,10 +618,12 @@ ${imports.join("\n")}
 // on whether this is a generated build or an ejected project.
 loadEnv({ path: ["../.env", ".env"], quiet: true });
 
+// The version the app's package.json carries is the fallback, so a bumped
+// release shows up in the connector UI without a second edit here.
 export const app = {
 	name: config.name,
 	title: config.title,
-	version: config.version ?? "0.0.0",
+	version: config.version ?? ${JSON.stringify(version ?? "0.0.0")},
 	instructions: config.instructions,
 };
 
@@ -630,7 +632,13 @@ export async function registerApp(server: McpServer): Promise<void> {
 		tools: ${list(app.tools.map((t) => `{ name: "${t.name}", def: tool_${camel(t.name)} }`))},
 		widgets: ${list(app.widgets.map((w) => `{ name: "${w.name}", def: widget_${camel(w.name)} }`))},
 		flows: ${list(app.flows.map((f) => `flow_${camel(f.name)}`))},
-		docs: ${app.docs.length > 0 ? "docs" : "[]"},
+		// Served by the same Express app as /mcp, at the path each file's position
+		// produced. For the browser — a widget's fetch — not for the model.
+		endpoints: ${list(
+			app.endpoints.map(
+				(e) => `{ path: "${e.path}", def: endpoint_${camel(e.segments.join("-"))} }`,
+			),
+		)},
 		// Read off the template's ${STYLE_ENTRY}, which every view imports.
 		styleDomains: ${list(styleDomains.map((origin) => `"${origin}"`))},
 	});
@@ -638,22 +646,6 @@ export async function registerApp(server: McpServer): Promise<void> {
 `;
 }
 
-/**
- * Docs are inlined into a module rather than read from disk, so they survive a
- * serverless bundle with no filesystem.
- */
-function generateDocs(app, { runtime }) {
-	return `// Generated from docs/*.md.
-import type { DocEntry } from "${runtime.index}";
-
-export const docs: DocEntry[] = ${JSON.stringify(
-		app.docs.map((doc) => ({ slug: doc.slug, title: doc.title, body: doc.body })),
-		null,
-		2,
-	)};
-`;
-}
-
 function generateWidgetShim(widget, layout) {
 	// From `src/views/` up to `src/`, then out to the app's source.
 	const from = `../${basename(layout.appDir)}`;
@@ -740,7 +732,6 @@ function generateBiome(template, layout) {
 				// Generated and vendored code is not the app author's to fix.
 				`!${layout.runtimeDir}/**`,
 				"!src/server.ts",
-				"!src/docs.ts",
 				"!src/views/**",
 				...negative,
 			],
@@ -861,7 +852,7 @@ function assertSeam(template) {
 
 	throw new Error(
 		`the template at ${template.source} never calls ${SEAM.symbol}(), so this app's\n` +
-			`  tools, widgets, flows, and docs would be built and then silently dropped.\n\n` +
+			`  tools, widgets and flows would be built and then silently dropped.\n\n` +
 			`  Add to its ${SEAM.file}:\n\n` +
 			`    import { app, registerApp } from "./waniwani.js";\n\n` +
 			`    const server = new McpServer(\n` +
@@ -999,14 +990,19 @@ export function generate(app, { template, layout: layoutName = "build", outDir }
 		}
 	}
 
+	const appPackageJsonPath = join(app.root, "package.json");
+	const appPackageJson = existsSync(appPackageJsonPath)
+		? JSON.parse(readFileSync(appPackageJsonPath, "utf-8"))
+		: undefined;
+
 	emit(
 		"src/waniwani.ts",
-		generateServerApp(app, layout, { runtime, styleDomains: templateStyleDomains(template) }),
+		generateServerApp(app, layout, {
+			runtime,
+			styleDomains: templateStyleDomains(template),
+			version: appPackageJson?.version,
+		}),
 	);
-	if (app.docs.length > 0) {
-		emit("src/docs.ts", generateDocs(app, { runtime }));
-	}
-
 	// `src/views/` is shared: the template's own views sit alongside the app's,
 	// so it cannot be wiped. Only the entries a previous build wrote are
 	// removed, which is what clears a widget the app has since deleted.
@@ -1019,11 +1015,6 @@ export function generate(app, { template, layout: layoutName = "build", outDir }
 		emit(`src/views/${widget.name}.tsx`, generateWidgetShim(widget, layout));
 	}
 
-	const appPackageJsonPath = join(app.root, "package.json");
-	const appPackageJson = existsSync(appPackageJsonPath)
-		? JSON.parse(readFileSync(appPackageJsonPath, "utf-8"))
-		: undefined;
-
 	const { packageJson, overrides } = generatePackageJson(app, appPackageJson, template, layout);
 
 	emit("tsconfig.json", `${JSON.stringify(generateTsconfig(template, layout), null, 2)}\n`);
@@ -1046,9 +1037,14 @@ export function generate(app, { template, layout: layoutName = "build", outDir }
 				sha: template.sha,
 				local: template.local,
 				manifest: manifest ? MANIFEST_FILE : undefined,
-				// What survived to the end: the generated files land on top of
-				// the copy, so the raw list overstates it.
-				files: fromTemplate.filter((file) => existsSync(join(root, file))),
+				// 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
+				// emitting one — `src/docs.ts` when docs left the framework —
+				// cleans up the copy the previous build left behind.
+				files: [...new Set([...fromTemplate, ...GENERATED])].filter((file) =>
+					existsSync(join(root, file)),
+				),
 				// Tracked separately because `src/views/` is shared with the
 				// template — the next build needs to know which entries were
 				// ours before it removes any.

package/cli/env.mjs

@@ -0,0 +1,37 @@
+/**
+ * The app's `.env`, loaded into this CLI's own environment.
+ *
+ * Two problems make this the only place it can happen.
+ *
+ * The framework runs from the generated project, so `process.cwd()` is
+ * `.waniwani/` and a bare `dotenv/config` looks for `.waniwani/.env` — a file
+ * nobody wrote. The app's `.env` sits one level up, next to `waniwani.config.ts`.
+ *
+ * Loading it from generated code inside that project is too late anyway. ESM
+ * evaluates a module's imports before its body, so by the time any line of
+ * `src/waniwani.ts` runs, every app module it imports has already been
+ * evaluated — and a module that builds an API client at import time has already
+ * read the empty environment and captured it. `createFlow(...).compile()` is the
+ * loud version of this: it throws at import time when `WANIWANI_API_KEY` is
+ * absent.
+ *
+ * Loading here, before anything is spawned, puts the variables in the
+ * environment every child process inherits, whatever order its modules load in.
+ * Hosted deploys set their variables on the platform and never reach this path.
+ */
+
+import { join } from "node:path";
+import dotenv from "dotenv";
+
+const loaded = new Set();
+
+/**
+ * `.env.local` before `.env`: the first file to define a variable wins, and
+ * dotenv never overwrites one already in the environment, so a value exported in
+ * the shell or set by CI outranks both files.
+ */
+export function loadAppEnv(root) {
+	if (loaded.has(root)) return;
+	loaded.add(root);
+	dotenv.config({ path: [join(root, ".env.local"), join(root, ".env")], quiet: true });
+}

package/cli/framework.mjs

@@ -91,7 +91,6 @@ function reword(line) {
  *
  * The framework's own tunnel is one of those lines. No command here asks for it,
  * so what arrives is its offer of one, and the emoji it carries drops the line.
- * A public hostname comes from `waniwani tunnel` instead (see ./tunnel.mjs).
  *
  * Each pattern leads with `\W*` to absorb whatever emoji prefixes the line and
  * ends at `$`, so a rule reads the framework's whole line and can't fire on an