@emseepea/create-openapi-backed-server 0.0.0 → 0.0.1

package/README.md

@@ -0,0 +1,93 @@
+# `@emseepea/create-openapi-backed-server`
+
+This directory is both the maintained example and its public npm initializer.
+
+## Use This Template
+
+Use this template when the JSON API you call has an OpenAPI 3 or Swagger 2
+contract and you want generated TypeScript and Zod validation at the backend
+boundary. Use the [API-backed server template](../api-backed-server/README.md)
+when no usable machine-readable contract exists.
+
+## Create a Project
+
+```sh
+npm init @emseepea/openapi-backed-server -- my-server
+```
+
+<!-- generated-project-readme -->
+
+## OpenAPI-Backed Pet Lookup
+
+The `get-pet` tool looks up one pet in
+[Swagger Petstore](https://petstore3.swagger.io/) by a positive identifier.
+The backend path parameters, response TypeScript declarations, and response
+validator come from the committed OpenAPI contract. The public MCP input and
+output remain separately described and bounded by the application.
+
+The canonical contract is
+[`contracts/petstore.openapi.json`](contracts/petstore.openapi.json). It was
+retrieved on 11 September 2026 from the exact
+[Swagger Petstore OpenAPI 3 endpoint](https://petstore3.swagger.io/api/v3/openapi.json)
+at version `1.0.27`; the committed file has SHA-256
+`f50a32e57d10018049bcd51c28bcb47f8e595563f7583cedaa9e7134376cec62`.
+
+The corresponding
+[upstream source at revision `d57941e`](https://github.com/swagger-api/swagger-petstore/blob/d57941e8fe959e508796b27469b1e8bba73392dc/src/main/resources/openapi.yaml)
+identifies the contract as Apache-2.0 licensed.
+
+The generation script accepts only local JSON Pointer references beginning
+with `#/`. It rejects web and relative-file references before conversion and
+again after Swagger 2 conversion. Generation, build, tests, start, and request
+handling never fetch a contract.
+
+## Generate Types and Validators
+
+Edit the local contract, then regenerate and review the diff:
+
+```sh
+npm run generate
+npm run generate:check
+```
+
+The checked-in files under `src/generated/` use `typed-openapi` with Zod 4,
+strict validation, the `getPetById` operation filter, and no generated HTTP
+client. Normal builds use these files without running the generator.
+
+The local
+[`test/fixtures/petstore.swagger.yaml`](test/fixtures/petstore.swagger.yaml)
+proves the older Swagger 2 import path. It is converted to OpenAPI 3 and sent
+through the same generator; it is not a second application template.
+
+## Run
+
+```sh
+npm install
+npm run build
+npm start
+```
+
+The MCP endpoint is `http://127.0.0.1:3000/mcp`.
+
+## Choose Open or Protected Access
+
+The starter is open by default. To protect it, pass an `access` policy and an
+`authentication` adapter to `createBackendExample`. The ordinary tests show
+the protected composition.
+
+## Check This Example
+
+Run generation drift, build, mapping, validation, and MCP checks:
+
+```sh
+npm run generate:check
+npm test
+```
+
+Run the language-model tool-choice and understanding check separately:
+
+```sh
+npm run test:llm
+```
+
+If Claude is not already signed in, run `claude auth login` first.

package/initializer-dist/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Windy Road Technology Pty. Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/initializer-dist/create.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+
+import { cp, mkdir, mkdtemp, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+
+const [destination, ...extra] = process.argv.slice(2);
+if (extra.length > 0 || !destination || !/^[a-z0-9][a-z0-9._-]*$/.test(destination)) {
+  throw new Error("Provide one simple lowercase destination name, such as my-server");
+}
+
+const target = resolve(destination);
+if (basename(target) !== destination) throw new Error("The destination must not contain a path");
+const staging = await mkdtemp(join(dirname(target), ".emseepea-create-"));
+
+try {
+  await copyContents(new URL("./template/", import.meta.url), staging);
+  const manifestPath = resolve(staging, "package.json");
+  const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+  await writeFile(manifestPath, `${JSON.stringify({ ...manifest, name: destination }, null, 2)}\n`);
+  await mkdir(target);
+  try {
+    await copyContents(staging, target);
+  } catch (error) {
+    await rm(target, { recursive: true, force: true });
+    throw error;
+  }
+} catch (error) {
+  if (["EEXIST", "ENOTEMPTY"].includes(error.code)) {
+    throw new Error(`The destination already exists: ${destination}`);
+  }
+  throw error;
+} finally {
+  await rm(staging, { recursive: true, force: true });
+}
+
+async function copyContents(source, destination) {
+  for (const entry of await readdir(source)) {
+    const from = source instanceof URL ? new URL(entry, source) : join(source, entry);
+    await cp(from, join(destination, entry), { recursive: true, errorOnExist: true, force: false });
+  }
+}
+
+console.log(`Created ${destination}.`);
+console.log(`Next: cd ${destination}; npm install; npm test; npm start`);

package/initializer-dist/template/README.md

@@ -0,0 +1,74 @@
+# OpenAPI-Backed Pet Lookup
+
+The `get-pet` tool looks up one pet in
+[Swagger Petstore](https://petstore3.swagger.io/) by a positive identifier.
+The backend path parameters, response TypeScript declarations, and response
+validator come from the committed OpenAPI contract. The public MCP input and
+output remain separately described and bounded by the application.
+
+The canonical contract is
+[`contracts/petstore.openapi.json`](contracts/petstore.openapi.json). It was
+retrieved on 11 September 2026 from the exact
+[Swagger Petstore OpenAPI 3 endpoint](https://petstore3.swagger.io/api/v3/openapi.json)
+at version `1.0.27`; the committed file has SHA-256
+`f50a32e57d10018049bcd51c28bcb47f8e595563f7583cedaa9e7134376cec62`.
+
+The corresponding
+[upstream source at revision `d57941e`](https://github.com/swagger-api/swagger-petstore/blob/d57941e8fe959e508796b27469b1e8bba73392dc/src/main/resources/openapi.yaml)
+identifies the contract as Apache-2.0 licensed.
+
+The generation script accepts only local JSON Pointer references beginning
+with `#/`. It rejects web and relative-file references before conversion and
+again after Swagger 2 conversion. Generation, build, tests, start, and request
+handling never fetch a contract.
+
+## Generate Types and Validators
+
+Edit the local contract, then regenerate and review the diff:
+
+```sh
+npm run generate
+npm run generate:check
+```
+
+The checked-in files under `src/generated/` use `typed-openapi` with Zod 4,
+strict validation, the `getPetById` operation filter, and no generated HTTP
+client. Normal builds use these files without running the generator.
+
+The local
+[`test/fixtures/petstore.swagger.yaml`](test/fixtures/petstore.swagger.yaml)
+proves the older Swagger 2 import path. It is converted to OpenAPI 3 and sent
+through the same generator; it is not a second application template.
+
+## Run
+
+```sh
+npm install
+npm run build
+npm start
+```
+
+The MCP endpoint is `http://127.0.0.1:3000/mcp`.
+
+## Choose Open or Protected Access
+
+The starter is open by default. To protect it, pass an `access` policy and an
+`authentication` adapter to `createBackendExample`. The ordinary tests show
+the protected composition.
+
+## Check This Example
+
+Run generation drift, build, mapping, validation, and MCP checks:
+
+```sh
+npm run generate:check
+npm test
+```
+
+Run the language-model tool-choice and understanding check separately:
+
+```sh
+npm run test:llm
+```
+
+If Claude is not already signed in, run `claude auth login` first.

package/initializer-dist/template/contracts/petstore.openapi.json

@@ -0,0 +1 @@
+{"openapi":"3.0.4","info":{"title":"Swagger Petstore - OpenAPI 3.0","description":"This is a sample Pet Store Server based on the OpenAPI 3.0 specification.  You can find out more about\nSwagger at [https://swagger.io](https://swagger.io). In the third iteration of the pet store, we've switched to the design first approach!\nYou can now help us improve the API whether it's by making changes to the definition itself or to the code.\nThat way, with time, we can improve the API in general, and expose some of the new features in OAS3.\n\nSome useful links:\n- [The Pet Store repository](https://github.com/swagger-api/swagger-petstore)\n- [The source API definition for the Pet Store](https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml)","termsOfService":"https://swagger.io/terms/","contact":{"email":"apiteam@swagger.io"},"license":{"name":"Apache 2.0","url":"https://www.apache.org/licenses/LICENSE-2.0.html"},"version":"1.0.27"},"externalDocs":{"description":"Find out more about Swagger","url":"https://swagger.io"},"servers":[{"url":"/api/v3"}],"tags":[{"name":"pet","description":"Everything about your Pets","externalDocs":{"description":"Find out more","url":"https://swagger.io"}},{"name":"store","description":"Access to Petstore orders","externalDocs":{"description":"Find out more about our store","url":"https://swagger.io"}},{"name":"user","description":"Operations about user"}],"paths":{"/pet":{"put":{"tags":["pet"],"summary":"Update an existing pet.","description":"Update an existing pet by Id.","operationId":"updatePet","requestBody":{"description":"Update an existent pet in the store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pet"}},"application/xml":{"schema":{"$ref":"#/components/schemas/Pet"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/Pet"}}},"required":true},"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pet"}},"application/xml":{"schema":{"$ref":"#/components/schemas/Pet"}}}},"400":{"description":"Invalid ID supplied"},"404":{"description":"Pet not found"},"422":{"description":"Validation exception"},"default":{"description":"Unexpected error"}},"security":[{"petstore_auth":["write:pets","read:pets"]}]},"post":{"tags":["pet"],"summary":"Add a new pet to the store.","description":"Add a new pet to the store.","operationId":"addPet","requestBody":{"description":"Create a new pet in the store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pet"}},"application/xml":{"schema":{"$ref":"#/components/schemas/Pet"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/Pet"}}},"required":true},"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pet"}},"application/xml":{"schema":{"$ref":"#/components/schemas/Pet"}}}},"400":{"description":"Invalid input"},"422":{"description":"Validation exception"},"default":{"description":"Unexpected error"}},"security":[{"petstore_auth":["write:pets","read:pets"]}]}},"/pet/findByStatus":{"get":{"tags":["pet"],"summary":"Finds Pets by status.","description":"Multiple status values can be provided with comma separated strings.","operationId":"findPetsByStatus","parameters":[{"name":"status","in":"query","description":"Status values that need to be considered for filter","required":true,"explode":true,"schema":{"type":"string","default":"available","enum":["available","pending","sold"]}}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Pet"}}},"application/xml":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Pet"}}}}},"400":{"description":"Invalid status value"},"default":{"description":"Unexpected error"}},"security":[{"petstore_auth":["write:pets","read:pets"]}]}},"/pet/findByTags":{"get":{"tags":["pet"],"summary":"Finds Pets by tags.","description":"Multiple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing.","operationId":"findPetsByTags","parameters":[{"name":"tags","in":"query","description":"Tags to filter by","required":true,"explode":true,"schema":{"type":"array","items":{"type":"string"}}}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Pet"}}},"application/xml":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Pet"}}}}},"400":{"description":"Invalid tag value"},"default":{"description":"Unexpected error"}},"security":[{"petstore_auth":["write:pets","read:pets"]}]}},"/pet/{petId}":{"get":{"tags":["pet"],"summary":"Find pet by ID.","description":"Returns a single pet.","operationId":"getPetById","parameters":[{"name":"petId","in":"path","description":"ID of pet to return","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pet"}},"application/xml":{"schema":{"$ref":"#/components/schemas/Pet"}}}},"400":{"description":"Invalid ID supplied"},"404":{"description":"Pet not found"},"default":{"description":"Unexpected error"}},"security":[{"api_key":[]},{"petstore_auth":["write:pets","read:pets"]}]},"post":{"tags":["pet"],"summary":"Updates a pet in the store with form data.","description":"Updates a pet resource based on the form data.","operationId":"updatePetWithForm","parameters":[{"name":"petId","in":"path","description":"ID of pet that needs to be updated","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"name","in":"query","description":"Name of pet that needs to be updated","schema":{"type":"string"}},{"name":"status","in":"query","description":"Status of pet that needs to be updated","schema":{"type":"string"}}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pet"}},"application/xml":{"schema":{"$ref":"#/components/schemas/Pet"}}}},"400":{"description":"Invalid input"},"default":{"description":"Unexpected error"}},"security":[{"petstore_auth":["write:pets","read:pets"]}]},"delete":{"tags":["pet"],"summary":"Deletes a pet.","description":"Delete a pet.","operationId":"deletePet","parameters":[{"name":"api_key","in":"header","description":"","required":false,"schema":{"type":"string"}},{"name":"petId","in":"path","description":"Pet id to delete","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"Pet deleted"},"400":{"description":"Invalid pet value"},"default":{"description":"Unexpected error"}},"security":[{"petstore_auth":["write:pets","read:pets"]}]}},"/pet/{petId}/uploadImage":{"post":{"tags":["pet"],"summary":"Uploads an image.","description":"Upload image of the pet.","operationId":"uploadFile","parameters":[{"name":"petId","in":"path","description":"ID of pet to update","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"additionalMetadata","in":"query","description":"Additional Metadata","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"400":{"description":"No file uploaded"},"404":{"description":"Pet not found"},"default":{"description":"Unexpected error"}},"security":[{"petstore_auth":["write:pets","read:pets"]}]}},"/store/inventory":{"get":{"tags":["store"],"summary":"Returns pet inventories by status.","description":"Returns a map of status codes to quantities.","operationId":"getInventory","responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"integer","format":"int32"}}}}},"default":{"description":"Unexpected error"}},"security":[{"api_key":[]}]}},"/store/order":{"post":{"tags":["store"],"summary":"Place an order for a pet.","description":"Place a new order in the store.","operationId":"placeOrder","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}},"application/xml":{"schema":{"$ref":"#/components/schemas/Order"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/Order"}}}},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"400":{"description":"Invalid input"},"422":{"description":"Validation exception"},"default":{"description":"Unexpected error"}}}},"/store/order/{orderId}":{"get":{"tags":["store"],"summary":"Find purchase order by ID.","description":"For valid response try integer IDs with value <= 5 or > 10. Other values will generate exceptions.","operationId":"getOrderById","parameters":[{"name":"orderId","in":"path","description":"ID of order that needs to be fetched","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}},"application/xml":{"schema":{"$ref":"#/components/schemas/Order"}}}},"400":{"description":"Invalid ID supplied"},"404":{"description":"Order not found"},"default":{"description":"Unexpected error"}}},"delete":{"tags":["store"],"summary":"Delete purchase order by identifier.","description":"For valid response try integer IDs with value < 1000. Anything above 1000 or non-integers will generate API errors.","operationId":"deleteOrder","parameters":[{"name":"orderId","in":"path","description":"ID of the order that needs to be deleted","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"order deleted"},"400":{"description":"Invalid ID supplied"},"404":{"description":"Order not found"},"default":{"description":"Unexpected error"}}}},"/user":{"post":{"tags":["user"],"summary":"Create user.","description":"This can only be done by the logged in user.","operationId":"createUser","requestBody":{"description":"Created user object","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}},"application/xml":{"schema":{"$ref":"#/components/schemas/User"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/User"}}}},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}},"application/xml":{"schema":{"$ref":"#/components/schemas/User"}}}},"default":{"description":"Unexpected error"}}}},"/user/createWithList":{"post":{"tags":["user"],"summary":"Creates list of users with given input array.","description":"Creates list of users with given input array.","operationId":"createUsersWithListInput","requestBody":{"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/User"}}}}},"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}},"application/xml":{"schema":{"$ref":"#/components/schemas/User"}}}},"default":{"description":"Unexpected error"}}}},"/user/login":{"get":{"tags":["user"],"summary":"Logs user into the system.","description":"Log into the system.","operationId":"loginUser","parameters":[{"name":"username","in":"query","description":"The user name for login","required":false,"schema":{"type":"string"}},{"name":"password","in":"query","description":"The password for login in clear text","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"successful operation","headers":{"X-Rate-Limit":{"description":"calls per hour allowed by the user","schema":{"type":"integer","format":"int32"}},"X-Expires-After":{"description":"date in UTC when token expires","schema":{"type":"string","format":"date-time"}}},"content":{"application/xml":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"string"}}}},"400":{"description":"Invalid username/password supplied"},"default":{"description":"Unexpected error"}}}},"/user/logout":{"get":{"tags":["user"],"summary":"Logs out current logged in user session.","description":"Log user out of the system.","operationId":"logoutUser","parameters":[],"responses":{"200":{"description":"successful operation"},"default":{"description":"Unexpected error"}}}},"/user/{username}":{"get":{"tags":["user"],"summary":"Get user by user name.","description":"Get user detail based on username.","operationId":"getUserByName","parameters":[{"name":"username","in":"path","description":"The name that needs to be fetched. Use user1 for testing","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}},"application/xml":{"schema":{"$ref":"#/components/schemas/User"}}}},"400":{"description":"Invalid username supplied"},"404":{"description":"User not found"},"default":{"description":"Unexpected error"}}},"put":{"tags":["user"],"summary":"Update user resource.","description":"This can only be done by the logged in user.","operationId":"updateUser","parameters":[{"name":"username","in":"path","description":"name that need to be deleted","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Update an existent user in the store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}},"application/xml":{"schema":{"$ref":"#/components/schemas/User"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/User"}}}},"responses":{"200":{"description":"successful operation"},"400":{"description":"bad request"},"404":{"description":"user not found"},"default":{"description":"Unexpected error"}}},"delete":{"tags":["user"],"summary":"Delete user resource.","description":"This can only be done by the logged in user.","operationId":"deleteUser","parameters":[{"name":"username","in":"path","description":"The name that needs to be deleted","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"User deleted"},"400":{"description":"Invalid username supplied"},"404":{"description":"User not found"},"default":{"description":"Unexpected error"}}}}},"components":{"schemas":{"Order":{"type":"object","properties":{"id":{"type":"integer","format":"int64","example":10},"petId":{"type":"integer","format":"int64","example":198772},"quantity":{"type":"integer","format":"int32","example":7},"shipDate":{"type":"string","format":"date-time"},"status":{"type":"string","description":"Order Status","example":"approved","enum":["placed","approved","delivered"]},"complete":{"type":"boolean"}},"xml":{"name":"order"}},"Category":{"type":"object","properties":{"id":{"type":"integer","format":"int64","example":1},"name":{"type":"string","example":"Dogs"}},"xml":{"name":"category"}},"User":{"type":"object","properties":{"id":{"type":"integer","format":"int64","example":10},"username":{"type":"string","example":"theUser"},"firstName":{"type":"string","example":"John"},"lastName":{"type":"string","example":"James"},"email":{"type":"string","example":"john@email.com"},"password":{"type":"string","example":"12345"},"phone":{"type":"string","example":"12345"},"userStatus":{"type":"integer","description":"User Status","format":"int32","example":1}},"xml":{"name":"user"}},"Tag":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"name":{"type":"string"}},"xml":{"name":"tag"}},"Pet":{"required":["name","photoUrls"],"type":"object","properties":{"id":{"type":"integer","format":"int64","example":10},"name":{"type":"string","example":"doggie"},"category":{"$ref":"#/components/schemas/Category"},"photoUrls":{"type":"array","xml":{"wrapped":true},"items":{"type":"string","xml":{"name":"photoUrl"}}},"tags":{"type":"array","xml":{"wrapped":true},"items":{"$ref":"#/components/schemas/Tag"}},"status":{"type":"string","description":"pet status in the store","enum":["available","pending","sold"]}},"xml":{"name":"pet"}},"ApiResponse":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"type":{"type":"string"},"message":{"type":"string"}},"xml":{"name":"##default"}}},"requestBodies":{"Pet":{"description":"Pet object that needs to be added to the store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pet"}},"application/xml":{"schema":{"$ref":"#/components/schemas/Pet"}}}},"UserArray":{"description":"List of user object","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/User"}}}}}},"securitySchemes":{"petstore_auth":{"type":"oauth2","flows":{"implicit":{"authorizationUrl":"https://petstore3.swagger.io/oauth/authorize","scopes":{"write:pets":"modify pets in your account","read:pets":"read your pets"}}}},"api_key":{"type":"apiKey","name":"api_key","in":"header"}}}}

package/initializer-dist/template/eval/meaning.test.mjs

@@ -0,0 +1,20 @@
+import test from "node:test";
+import {
+  assertNoNegativeFeedback,
+  assertResponseContains,
+  assertResponseMeaning,
+  assertToolCallsWithOptionalFeedback,
+  createConversation,
+} from "@emseepea/testing/semantic";
+
+test("looks up a pet and explains its status", async (t) => {
+  const chat = await createConversation(t, {
+    server: new URL("../test-support/llm-server.mjs", import.meta.url),
+  });
+  const response = await chat.send("Look up Swagger Petstore pet 7. What is its name and status?");
+
+  await assertToolCallsWithOptionalFeedback(response, [{ name: "get-pet", arguments: { petId: 7 } }]);
+  assertResponseContains(response, "Sweet Pea");
+  await assertResponseMeaning(response, { expected: "Pet 7 is named Sweet Pea and is available." });
+  assertNoNegativeFeedback(response);
+});

package/initializer-dist/template/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "emseepea-starter",
+  "version": "0.0.0",
+  "description": "Create an Em See Pea server backed by an OpenAPI-described web API.",
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "generate": "node scripts/generate.mjs",
+    "generate:check": "node scripts/check-generated.mjs",
+    "start": "node dist/server.js",
+    "test": "npm run generate:check && npm run license:check && npm run build && npm run test:built",
+    "test:built": "node --test test/*.test.mjs",
+    "test:llm": "npm run build && npm run test:llm:built",
+    "test:llm:built": "emseepea-test eval",
+    "lint": "oxlint src test eval scripts test-support",
+    "license:check": "node scripts/check-licenses.mjs"
+  },
+  "devDependencies": {
+    "@emseepea/feedback": "0.2.1",
+    "@scalar/openapi-upgrader": "0.2.15",
+    "@emseepea/testing": "0.9.4",
+    "@modelcontextprotocol/client": "2.0.0",
+    "@types/node": "24.13.3",
+    "oxlint": "1.80.0",
+    "typed-openapi": "4.0.1",
+    "typescript": "6.0.3",
+    "yaml": "2.9.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "private": true,
+  "dependencies": {
+    "@emseepea/server": "0.7.0",
+    "zod": "4.4.3"
+  }
+}

package/initializer-dist/template/scripts/check-generated.mjs

@@ -0,0 +1,22 @@
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import { canonicalArtifacts, generatedArtifacts, upgradeSwagger } from "./generate.mjs";
+
+const generated = await canonicalArtifacts();
+assert.match(generated.schemas, /from "zod"/);
+assert.match(generated.schemas, /get_GetPetById/);
+assert.doesNotMatch(generated.schemas, /\bfetch\s*\(/);
+assert.match(generated.types, /namespace Endpoints/);
+assert.equal(
+  await readFile(new URL("../src/generated/petstore.ts", import.meta.url), "utf8"),
+  generated.schemas,
+  "generated OpenAPI schemas are stale",
+);
+assert.equal(
+  await readFile(new URL("../src/generated/petstore.types.d.ts", import.meta.url), "utf8"),
+  generated.types,
+  "generated OpenAPI declarations are stale",
+);
+const swagger = upgradeSwagger(await readFile(new URL("../test/fixtures/petstore.swagger.yaml", import.meta.url), "utf8"));
+assert.equal(swagger.paths["/pet/{petId}"].get.operationId, "getPetById");
+assert.match((await generatedArtifacts(swagger)).schemas, /get_GetPetById/);

package/initializer-dist/template/scripts/check-licenses.mjs

@@ -0,0 +1,29 @@
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
+
+const require = createRequire(import.meta.url);
+
+async function manifest(name) {
+  const root = path.dirname(path.dirname(require.resolve(name)));
+  return JSON.parse(await readFile(path.join(root, "package.json"), "utf8"));
+}
+
+const typedOpenapiRoot = path.dirname(path.dirname(require.resolve("typed-openapi")));
+const typedOpenapiLicense = await readFile(path.join(typedOpenapiRoot, "LICENSE"));
+assert.equal((await manifest("typed-openapi")).version, "4.0.1");
+assert.equal(
+  createHash("sha256").update(typedOpenapiLicense).digest("hex"),
+  "ec37c1598e498ddfad278fc180baaf2fd2545d39754075cd0a76dbe85198c90c",
+  "typed-openapi's shipped MIT licence changed",
+);
+assert.deepEqual(
+  [await manifest("@scalar/openapi-upgrader"), await manifest("yaml")]
+    .map(({ name, version, license }) => ({ name, version, license })),
+  [
+    { name: "@scalar/openapi-upgrader", version: "0.2.15", license: "MIT" },
+    { name: "yaml", version: "2.9.0", license: "ISC" },
+  ],
+);

package/initializer-dist/template/scripts/generate.mjs

@@ -0,0 +1,74 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { upgradeFromTwoToThree } from "@scalar/openapi-upgrader/2.0-to-3.0";
+import { generateClientFiles } from "typed-openapi/node";
+import { parse } from "yaml";
+
+const contract = new URL("../contracts/petstore.openapi.json", import.meta.url);
+
+export function assertLocalReferences(value, location = "$") {
+  if (!value || typeof value !== "object") return;
+  if ("$ref" in value) {
+    assert.equal(typeof value.$ref, "string", `${location} has a non-string $ref`);
+    assert.match(value.$ref, /^#\//, `${location} has a non-local $ref`);
+  }
+  for (const [key, child] of Object.entries(value)) {
+    assertLocalReferences(child, `${location}.${key}`);
+  }
+}
+
+export function parseContract(source) {
+  const document = parse(source);
+  assertLocalReferences(document);
+  return document;
+}
+
+export function upgradeSwagger(source) {
+  const upgraded = upgradeFromTwoToThree(parseContract(source));
+  assertLocalReferences(upgraded);
+  return upgraded;
+}
+
+export async function generatedArtifacts(document) {
+  assertLocalReferences(document);
+  const directory = await mkdtemp(path.join(tmpdir(), "emseepea-openapi-"));
+  try {
+    const input = path.join(directory, "petstore.json");
+    const output = path.join(directory, "petstore.ts");
+    await writeFile(input, `${JSON.stringify(document)}\n`);
+    await generateClientFiles(input, {
+      output,
+      runtime: "zod",
+      validation: "strict",
+      includeClient: false,
+      includeDescriptions: true,
+      endpoint: "getPetById",
+    });
+    return {
+      schemas: normalize(await readFile(output, "utf8")),
+      types: normalize(await readFile(path.join(directory, "petstore.types.d.ts"), "utf8")),
+    };
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+}
+
+function normalize(source) {
+  return `${source.split("\n").map((line) => line.trimEnd()).join("\n").trim()}\n`;
+}
+
+export async function canonicalArtifacts() {
+  return generatedArtifacts(parseContract(await readFile(contract, "utf8")));
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  const generated = await canonicalArtifacts();
+  await mkdir(new URL("../src/generated/", import.meta.url), { recursive: true });
+  await Promise.all([
+    writeFile(new URL("../src/generated/petstore.ts", import.meta.url), generated.schemas),
+    writeFile(new URL("../src/generated/petstore.types.d.ts", import.meta.url), generated.types),
+  ]);
+}

package/initializer-dist/template/src/app.ts

@@ -0,0 +1,25 @@
+import {
+  createEmseepea,
+  discoverCapabilities,
+  type AccessPolicy,
+  type EmseepeaExtensions,
+} from "@emseepea/server";
+import type { JsonHttpClient } from "@emseepea/server/http";
+
+export interface BackendExampleOptions extends EmseepeaExtensions {
+  readonly access?: AccessPolicy;
+}
+
+export async function createBackendExample(
+  client: JsonHttpClient,
+  options: BackendExampleOptions = {},
+): Promise<ReturnType<typeof createEmseepea>> {
+  const { access = { access: "public" }, ...extensions } = options;
+  return createEmseepea({
+    name: "emseepea-openapi-backed-server",
+    version: "0.0.0",
+    instructions: "Use get-pet to look up a pet in Swagger Petstore by identifier.",
+    ...await discoverCapabilities(new URL("./capabilities/", import.meta.url), { client, access }),
+    ...extensions,
+  });
+}

package/initializer-dist/template/src/capabilities/tool.get-pet.ts

@@ -0,0 +1,60 @@
+import { defineMappedTool, type AccessPolicy, type CapabilityModuleFactory } from "@emseepea/server";
+import type { JsonHttpClient } from "@emseepea/server/http";
+import { z } from "zod";
+import { get_GetPetById } from "../generated/petstore.js";
+
+export interface BackendExampleContext {
+  readonly client: JsonHttpClient;
+  readonly access: AccessPolicy;
+}
+
+const inputSchema = z.object({
+  petId: z.number().int().positive().max(Number.MAX_SAFE_INTEGER)
+    .describe("Positive Swagger Petstore identifier to look up."),
+});
+const outputSchema = z.object({
+  id: z.number().int().positive().describe("Identifier returned for the pet."),
+  name: z.string().min(1).max(200).describe("Name of the pet."),
+  status: z.enum(["available", "pending", "sold"]).optional()
+    .describe("Current Petstore availability when supplied."),
+  photoUrls: z.array(z.string().url().max(2_048)).max(10)
+    .describe("Up to ten photo URLs supplied by Petstore."),
+  source: z.literal("Swagger Petstore").describe("Data provider for this result."),
+});
+const backendInputSchema = z.object({
+  pathname: z.string().regex(/^\/api\/v3\/pet\/[1-9]\d*$/),
+  parameters: get_GetPetById.parameters.path,
+});
+const backendOutputSchema = z.object({
+  request: backendInputSchema,
+  payload: get_GetPetById.responses[200],
+});
+
+export default (({ client, access }) => defineMappedTool({
+  name: "get-pet",
+  ...access,
+  description: "Look up one pet by identifier in Swagger Petstore.",
+  inputSchema,
+  outputSchema,
+  backendInputSchema,
+  backendOutputSchema,
+  mapInput: ({ petId }) => ({
+    pathname: `/api/v3/pet/${petId}`,
+    parameters: { petId },
+  }),
+  async adapter(request, { signal, deadlineMs }) {
+    return {
+      request,
+      payload: await client.get({ pathname: request.pathname, signal, deadlineMs }),
+    };
+  },
+  mapOutput: ({ request, payload }) => ({
+    data: {
+      id: payload.id ?? request.parameters.petId,
+      name: payload.name,
+      status: payload.status,
+      photoUrls: payload.photoUrls,
+      source: "Swagger Petstore" as const,
+    },
+  }),
+})) satisfies CapabilityModuleFactory<BackendExampleContext>;

package/initializer-dist/template/src/generated/petstore.ts

@@ -0,0 +1,44 @@
+// @ts-nocheck
+import type * as __TypedOpenapi from "./petstore.types.js";
+
+  import { z } from "zod";
+
+// <Schemas>
+export type Category = __TypedOpenapi.Schemas.Category;
+export const Category = z.object({ id: z.number().int(), name: z.string() }).partial().catchall(z.unknown());
+
+export type Tag = __TypedOpenapi.Schemas.Tag;
+export const Tag = z.object({ id: z.number().int(), name: z.string() }).partial().catchall(z.unknown());
+
+export type Pet = __TypedOpenapi.Schemas.Pet;
+export const Pet = z.object({ id: z.number().int().optional(), name: z.string(), category: Category.optional(), photoUrls: z.array(z.string()), tags: z.array(Tag).optional(), status: z.enum(["available", "pending", "sold"]).describe("pet status in the store").optional() }).catchall(z.unknown());
+
+// </Schemas>
+
+// <Endpoints>
+export type get_GetPetById = __TypedOpenapi.Endpoints.get_GetPetById;
+export const get_GetPetById = {
+  method: z.literal("GET"),
+  path: z.literal("/pet/{petId}"),
+  requestFormat: z.literal("json"),
+  responseFormat: z.literal("json"),
+  parameters: { path: z.object({ petId: z.coerce.number().int() }).strict() },
+  responses: { 200: Pet, 400: z.unknown(), 404: z.unknown(), default: z.unknown() },
+};
+
+// </Endpoints>
+
+
+     // <EndpointByMethod>
+     export const EndpointByMethod = {
+     get: {
+           "/pet/{petId}": get_GetPetById
+         }
+     } satisfies { [M in keyof __TypedOpenapi.EndpointByMethod]: { [P in keyof __TypedOpenapi.EndpointByMethod[M]]: unknown } }
+     export type EndpointByMethod = __TypedOpenapi.EndpointByMethod;
+     // </EndpointByMethod>
+
+
+    // <EndpointByMethod.Shorthands>
+    export type GetEndpoints = EndpointByMethod["get"]
+    // </EndpointByMethod.Shorthands>

package/initializer-dist/template/src/generated/petstore.types.d.ts

@@ -0,0 +1,62 @@
+export namespace Schemas {
+    // <Schemas>
+  export type Category = Partial<{ id: number, name: string }>
+export type Tag = Partial<{ id: number, name: string }>
+export type Pet = ({
+  id?: number;
+  name: string;
+  category?: Category;
+  photoUrls: Array<string>;
+  tags?: Array<Tag>;
+  /**
+   * pet status in the store
+   */
+  status?: ("available" | "pending" | "sold");
+} & Record<string, unknown>)
+
+    // </Schemas>
+    }
+
+  export namespace Endpoints {
+  // <Endpoints>
+
+  /**
+ * Returns a single pet.
+ */
+export type get_GetPetById = {
+      method: "GET",
+      path: "/pet/{petId}",
+      requestFormat: "json",
+      responseFormat: "json",
+      parameters: {
+
+        path:  { petId: number },
+
+
+
+          }
+      responses: {200: Schemas.Pet,
+400: unknown,
+404: unknown,
+default: unknown,
+},
+
+    }
+
+  // </Endpoints>
+  }
+
+
+     // <EndpointByMethod>
+     export type EndpointByMethod = {
+     get: {
+           "/pet/{petId}": Endpoints.get_GetPetById
+         }
+     }
+
+     // </EndpointByMethod>
+
+
+    // <EndpointByMethod.Shorthands>
+    export type GetEndpoints = EndpointByMethod["get"]
+    // </EndpointByMethod.Shorthands>

package/initializer-dist/template/src/server.ts

@@ -0,0 +1,22 @@
+import { serveEmseepea } from "@emseepea/server";
+import { createJsonHttpClient } from "@emseepea/server/http";
+import { createBackendExample } from "./app.js";
+
+const client = createJsonHttpClient({
+  origin: "https://petstore3.swagger.io",
+  maxResponseBytes: 128 * 1024,
+});
+const running = await serveEmseepea(
+  await createBackendExample(client),
+  { port: Number.parseInt(process.env.PORT ?? "3000", 10) },
+);
+
+console.log(`Em See Pea OpenAPI-backed server example listening at ${running.url}`);
+
+async function shutdown(): Promise<void> {
+  await running.close();
+  process.exitCode = 0;
+}
+
+process.once("SIGINT", () => void shutdown());
+process.once("SIGTERM", () => void shutdown());

package/initializer-dist/template/test/fixtures/petstore.swagger.yaml

@@ -0,0 +1,38 @@
+swagger: "2.0"
+info:
+  title: Petstore fixture
+  version: "1.0.0"
+basePath: /v2
+schemes: [https]
+paths:
+  /pet/{petId}:
+    get:
+      operationId: getPetById
+      parameters:
+        - name: petId
+          in: path
+          required: true
+          type: integer
+          format: int64
+          minimum: 1
+      responses:
+        "200":
+          description: successful operation
+          schema:
+            $ref: "#/definitions/Pet"
+definitions:
+  Pet:
+    type: object
+    required: [id, name, photoUrls]
+    properties:
+      id:
+        type: integer
+        format: int64
+      name:
+        type: string
+      photoUrls:
+        type: array
+        items: { type: string }
+      status:
+        type: string
+        enum: [available, pending, sold]

package/initializer-dist/template/test/server.test.mjs

@@ -0,0 +1,191 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
+import { createEmseepea, defineMappedTool, serveEmseepea } from "@emseepea/server";
+import { insecureTestAuthentication, startEmseepea } from "@emseepea/testing";
+import { z } from "zod";
+import { createBackendExample } from "../dist/app.js";
+import { assertLocalReferences, generatedArtifacts } from "../scripts/generate.mjs";
+import { get_GetPetById, Pet } from "../dist/generated/petstore.js";
+import { petstoreFixture } from "../test-support/petstore-fixture.mjs";
+
+test("the OpenAPI-backed example uses generated request and response validation", async () => {
+  const requests = [];
+  let response = petstoreFixture;
+  const app = await createBackendExample({
+    async get(options) {
+      requests.push(options);
+      if (response instanceof Error) throw response;
+      return response;
+    },
+  });
+  const running = await serveEmseepea(app, { port: 0 });
+  const client = new Client(
+    { name: "openapi-backed-example-test", version: "0.0.0" },
+    { versionNegotiation: { mode: { pin: "2026-07-28" } } },
+  );
+  await client.connect(new StreamableHTTPClientTransport(new URL(running.url)));
+
+  try {
+    const listed = await client.listTools();
+    assert.deepEqual(listed.tools.map(({ name }) => name), ["get-pet"]);
+
+    const invalidInput = await client.callTool({ name: "get-pet", arguments: { petId: 0 } });
+    assert.equal(invalidInput.isError, true);
+    assert.equal(requests.length, 0);
+
+    const result = await client.callTool({ name: "get-pet", arguments: { petId: 7 } });
+    assert.equal(result.isError, false);
+    assert.deepEqual(result.structuredContent, {
+      id: 7,
+      name: "Sweet Pea",
+      status: "available",
+      photoUrls: ["https://example.test/sweet-pea.jpg"],
+      source: "Swagger Petstore",
+    });
+    assert.equal(requests[0].pathname, "/api/v3/pet/7");
+    assert.equal(requests[0].signal instanceof AbortSignal, true);
+    assert.ok(requests[0].deadlineMs > Date.now());
+
+    response = { ...petstoreFixture, name: 42 };
+    const invalidProviderData = await client.callTool({ name: "get-pet", arguments: { petId: 7 } });
+    assert.equal(invalidProviderData.isError, true);
+    assert.doesNotMatch(JSON.stringify(invalidProviderData), /42|photoUrls/);
+
+    response = { ...petstoreFixture, private_note: "do not expose" };
+    const extraProviderData = await client.callTool({ name: "get-pet", arguments: { petId: 7 } });
+    assert.equal(extraProviderData.isError, false);
+    assert.equal("private_note" in extraProviderData.structuredContent, false);
+  } finally {
+    await client.close();
+    await running.close();
+  }
+});
+
+test("contract loading permits only fragment references", () => {
+  assert.doesNotThrow(() => assertLocalReferences({ $ref: "#/components/schemas/Pet" }));
+  assert.throws(() => assertLocalReferences({ $ref: "https://example.test/pet.yaml" }), /non-local/);
+  assert.throws(() => assertLocalReferences({ $ref: "pet.yaml#/Pet" }), /non-local/);
+});
+
+test("the generation entry point rejects non-local references", async () => {
+  await assert.rejects(
+    generatedArtifacts({ $ref: "https://example.test/pet.yaml" }),
+    /non-local/,
+  );
+  await assert.rejects(generatedArtifacts({ $ref: "pet.yaml#/Pet" }), /non-local/);
+});
+
+test("contract changes alter the generated declarations and validators", async () => {
+  const source = generationContract();
+  const baseline = await generatedArtifacts(source);
+  for (const mutate of [
+    (document) => { document.components.schemas.Pet.required = ["photoUrls"]; },
+    (document) => { delete document.components.schemas.Pet.properties.note; },
+    (document) => { document.components.schemas.Pet.properties.name.type = "integer"; },
+    (document) => { document.components.schemas.Pet.properties.status.enum.push("archived"); },
+  ]) {
+    const changed = structuredClone(source);
+    mutate(changed);
+    const regenerated = await generatedArtifacts(changed);
+    assert.notEqual(regenerated.schemas, baseline.schemas);
+    assert.notEqual(regenerated.types, baseline.types);
+  }
+  assert.equal(Pet.safeParse(petstoreFixture).success, true);
+  assert.equal(Pet.safeParse({ ...petstoreFixture, status: "archived" }).success, false);
+});
+
+test("an invalid mapped backend request makes no adapter call", async () => {
+  let adapterCalls = 0;
+  const tool = defineMappedTool({
+    name: "invalid-generated-request",
+    access: "public",
+    description: "Exercise the generated request boundary.",
+    inputSchema: z.object({ petId: z.number().int().positive() }),
+    outputSchema: z.object({ ok: z.boolean() }),
+    backendInputSchema: get_GetPetById.parameters.path,
+    backendOutputSchema: z.object({ ok: z.boolean() }),
+    mapInput: () => ({ petId: "not-an-integer" }),
+    adapter() {
+      adapterCalls += 1;
+      return { ok: true };
+    },
+    mapOutput: (data) => ({ data }),
+  });
+  const running = await serveEmseepea(createEmseepea({
+    name: "invalid-generated-request-test",
+    version: "0.0.0",
+    tools: [tool],
+  }), { port: 0 });
+  const client = new Client(
+    { name: "invalid-generated-request-test", version: "0.0.0" },
+    { versionNegotiation: { mode: { pin: "2026-07-28" } } },
+  );
+  await client.connect(new StreamableHTTPClientTransport(new URL(running.url)));
+  try {
+    const result = await client.callTool({ name: "invalid-generated-request", arguments: { petId: 7 } });
+    assert.equal(result.isError, true);
+    assert.equal(adapterCalls, 0);
+  } finally {
+    await client.close();
+    await running.close();
+  }
+});
+
+test("the same template composes protected access and observability", async (t) => {
+  const events = [];
+  const permissions = ["pets:read"];
+  const app = await createBackendExample(
+    { get: async () => petstoreFixture },
+    {
+      access: { access: "protected", requiredScopes: permissions },
+      authentication: insecureTestAuthentication(permissions),
+      observability: [{ id: "test-log", emit: (event) => events.push(event) }],
+    },
+  );
+  const running = await startEmseepea(t, app);
+  const client = await running.connect("test-token");
+  const result = await client.callTool({ name: "get-pet", arguments: { petId: 7 } });
+  assert.equal(result.isError, false);
+  assert.ok(events.some(({ capability }) => capability === "get-pet"));
+});
+
+function generationContract() {
+  return {
+    openapi: "3.0.4",
+    info: { title: "Generation fixture", version: "1.0.0" },
+    paths: {
+      "/pet/{petId}": {
+        get: {
+          operationId: "getPetById",
+          parameters: [{
+            name: "petId",
+            in: "path",
+            required: true,
+            schema: { type: "integer", minimum: 1 },
+          }],
+          responses: {
+            200: {
+              description: "Pet",
+              content: { "application/json": { schema: { $ref: "#/components/schemas/Pet" } } },
+            },
+          },
+        },
+      },
+    },
+    components: {
+      schemas: {
+        Pet: {
+          type: "object",
+          required: ["name", "photoUrls"],
+          properties: {
+            name: { type: "string" },
+            note: { type: "string" },
+            photoUrls: { type: "array", items: { type: "string" } },
+            status: { type: "string", enum: ["available", "pending", "sold"] },
+          },
+        },
+      },
+    },
+  };
+}

package/initializer-dist/template/test-support/llm-server.mjs

@@ -0,0 +1,28 @@
+import assert from "node:assert/strict";
+import { serveEmseepea } from "@emseepea/server";
+import { defineFeedbackSubmission } from "@emseepea/feedback";
+import { createBackendExample } from "../dist/app.js";
+import { petstoreFixture } from "./petstore-fixture.mjs";
+
+const client = {
+  async get({ pathname }) {
+    assert.equal(pathname, "/api/v3/pet/7");
+    return petstoreFixture;
+  },
+};
+const feedback = defineFeedbackSubmission({
+  access: "public",
+  backend: { submit: () => ({ id: crypto.randomUUID(), recordedAt: new Date().toISOString() }) },
+});
+const app = await createBackendExample(client, { additionalTools: [feedback] });
+const running = await serveEmseepea(app, { port: 0 });
+
+console.log(`Em See Pea OpenAPI-backed fixture listening at ${running.url}`);
+
+async function shutdown() {
+  await running.close();
+  process.exitCode = 0;
+}
+
+process.once("SIGINT", () => void shutdown());
+process.once("SIGTERM", () => void shutdown());

package/initializer-dist/template/test-support/petstore-fixture.mjs

@@ -0,0 +1,8 @@
+export const petstoreFixture = {
+  id: 7,
+  category: { id: 1, name: "peas" },
+  name: "Sweet Pea",
+  photoUrls: ["https://example.test/sweet-pea.jpg"],
+  tags: [{ id: 2, name: "flower" }],
+  status: "available",
+};

package/initializer-dist/template/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "target": "ES2023",
+    "types": ["node"],
+    "verbatimModuleSyntax": true
+  },
+  "include": ["src/**/*.ts"]
+}

package/package.json

@@ -1,13 +1,43 @@
 {
   "name": "@emseepea/create-openapi-backed-server",
-  "version": "0.0.0",
-  "description": "Bootstrap-only placeholder for npm trusted publishing. Do not install.",
+  "version": "0.0.1",
+  "description": "Create an Em See Pea server backed by an OpenAPI-described web API.",
   "license": "MIT",
   "type": "module",
-  "private": false,
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/emseepea/emseepea.git",
-    "directory": "examples/openapi-backed-server"
-  }
+  "starterDependencies": ["@emseepea/server", "zod"],
+  "scripts": {
+    "build": "npm run build:example && npm run build:initializer",
+    "build:example": "tsc -p tsconfig.json",
+    "build:initializer": "node ../../scripts/build-initializer.mjs",
+    "generate": "node scripts/generate.mjs",
+    "generate:check": "node scripts/check-generated.mjs",
+    "start": "node dist/server.js",
+    "test": "npm run generate:check && npm run license:check && npm run build && npm run test:built",
+    "test:built": "node --test test/*.test.mjs",
+    "test:llm": "npm run build && npm run test:llm:built",
+    "test:llm:built": "emseepea-test eval",
+    "lint": "oxlint src test eval scripts test-support",
+    "license:check": "node scripts/check-licenses.mjs",
+    "prepack": "npm run build:initializer"
+  },
+  "devDependencies": {
+    "@emseepea/feedback": "0.2.1",
+    "@emseepea/server": "0.7.0",
+    "@scalar/openapi-upgrader": "0.2.15",
+    "@emseepea/testing": "0.9.4",
+    "@modelcontextprotocol/client": "2.0.0",
+    "@types/node": "24.13.3",
+    "oxlint": "1.80.0",
+    "typed-openapi": "4.0.1",
+    "typescript": "6.0.3",
+    "yaml": "2.9.0",
+    "zod": "4.4.3"
+  },
+  "engines": { "node": ">=22" },
+  "repository": { "type": "git", "url": "git+https://github.com/emseepea/emseepea.git", "directory": "examples/openapi-backed-server" },
+  "homepage": "https://emseepea.github.io/emseepea/examples/",
+  "bugs": "https://github.com/emseepea/emseepea/issues",
+  "publishConfig": { "access": "public", "provenance": true },
+  "bin": { "create-openapi-backed-server": "./initializer-dist/create.mjs" },
+  "files": ["initializer-dist"]
 }