@nxgt/typespec 0.8.0 → 0.9.1

package/README.md

@@ -8,6 +8,10 @@ Each shape here is one the `@nxgt/*` packages already send on the wire.
 
 ## Install
 
+A new project needs no install of its own: `tsp init` with the package's
+template installs everything ([Start a project](#start-a-project)). For an
+existing project, install the library and its peers:
+
 ```sh
 bun add -d @nxgt/typespec @typespec/compiler @typespec/http @typespec/openapi @typespec/openapi3 @nxgt/openapi-codegen
 ```
@@ -16,6 +20,8 @@ bun add -d @nxgt/typespec @typespec/compiler @typespec/http @typespec/openapi @t
 are peer dependencies,
 and `typescript` 6 too, as for every `@nxgt` package. `@typespec/openapi3`
 compiles the spec, and `@nxgt/openapi-codegen` generates the code from it.
+The generator's CLI, `nxgt-openapi`, runs on [Bun](https://bun.sh): it needs
+`bun` on the PATH, even when called through `npx` or an npm script.
 Emit OpenAPI 3.1 or 3.2 in `tspconfig.yaml`: `@typespec/openapi3` emits 3.0
 by default, and the generator refuses it. Every convention here is compiled
 to both in CI, and generates the same code from either.
@@ -33,6 +39,35 @@ options:
 
 ## Usage
 
+### Start a project
+
+`tsp init` with the package's template starts an API project with these
+conventions in place. Run it in an empty directory, with
+[Bun](https://bun.sh) on the PATH for the generator:
+
+```sh
+npx --package=@typespec/compiler tsp init https://unpkg.com/@nxgt/typespec/templates/scaffolding.json \
+  --template nxgt -y --project-name petstore
+npx tsp compile .
+npx nxgt-openapi generate
+```
+
+It installs the compiler, `@typespec/http`, `@typespec/openapi`,
+`@typespec/openapi3`, this package and `@nxgt/openapi-codegen`, and writes:
+
+- `tspconfig.yaml`: the linter's recommended rules, and OpenAPI 3.1 written
+  to `openapi/openapi.yaml`;
+- `main.tsp`: the service in the namespace `Api`, with `@operationIds`, and a
+  `Users` resource with a paged, sorted list, `get`, `create`, `update` and
+  `delete`, and their error aliases;
+- `openapi-codegen.config.ts`: the generator's input, and `src/generated`
+  with the Hono routes;
+- `README.md`: the `api` and `api:check` scripts to add to `package.json`.
+
+Drop `-y` and its options to be asked instead. The next steps, serving the
+routes and renaming the resource, are in
+[Getting started](docs/guide/getting-started.md).
+
 ### A spec split across files
 
 A spec that grows is split by role: one file per resource's models, one per
@@ -513,6 +548,9 @@ envelope and the rate limit's headers.
 
 ## Traps
 
+- **`nxgt-openapi` fails with `env: 'bun': No such file or directory`**
+  without Bun on the PATH: install it, `curl -fsSL https://bun.sh/install | bash`
+  ([troubleshooting](docs/troubleshooting.md#env-bun-no-such-file-or-directory)).
 - **Do not declare a schema named `ValidationErrorBody`.** The generator
   declares it itself, and two schemas of that name fail with
   `name_collision`. `BadRequestBody` carries the `issues` instead.
@@ -570,6 +608,8 @@ envelope and the rate limit's headers.
 
 ## Documentation
 
+- [Getting started](docs/guide/getting-started.md): the `tsp init`
+  template, the files it writes, and the steps from the spec to a Hono route;
 - [Error replies](docs/guide/errors.md): the envelope, each response, the
   aliases by verb, and what the generator makes of them;
 - [Pagination](docs/guide/pagination.md): offset and cursor pages, and

package/docs/README.md

@@ -4,6 +4,7 @@ The [package README](../README.md) is the short version.
 
 | Page | Read it when |
 | --- | --- |
+| [Getting started](guide/getting-started.md) | starting a new API project from the `tsp init` template, up to a Hono route |
 | [Error replies](guide/errors.md) | declaring what an operation answers when it fails |
 | [Pagination](guide/pagination.md) | listing a collection a page at a time |
 | [Authentication](guide/auth.md) | protecting an operation with a `@nxgt/janus` session |

package/docs/guide/errors.md

@@ -162,7 +162,9 @@ its own way, through `onValidationError`, turns that off with the generator's
 | `Forbidden` | 403 | `ForbiddenBody` | authenticated, but not allowed; a `@nxgt/janus-hono` guard sends `AccessDenied` instead, and `janusErrors()` its own `{ code }` body ([Authentication](auth.md)) |
 | `NotFound` | 404 | `NotFoundBody` | nothing is there |
 | `Conflict` | 409 | `ConflictBody` | the request conflicts with the resource's state, such as a stale `version` |
+| `IdempotencyInProgress` | 409 | `ConflictBody` | the first request with this `Idempotency-Key` still runs; with the `RateLimit-*` headers and `Retry-After` ([Headers](headers.md)) |
 | `UnprocessableEntity` | 422 | `UnprocessableEntityBody` | well-formed, but not something the server can act on |
+| `IdempotencyKeyReused` | 422 | `UnprocessableEntityBody` | an `Idempotency-Key` sent again with another body; with the `RateLimit-*` headers ([Headers](headers.md)) |
 | `TooManyRequests` | 429 | `TooManyRequestsBody` | too many requests; with the `RateLimit-*` headers and `Retry-After` ([Headers](headers.md)) |
 | `InternalServerError` | 500 | `InternalServerErrorBody` | the server failed; with `validateResponses`, `@nxgt/openapi-hono` sends it with `errors.response-validation-failed` when a reply breaks the spec |
 | `ErrorResponse<Status>` | any | `ErrorBody<Status>` | any other status |

package/docs/guide/getting-started.md

@@ -0,0 +1,277 @@
+# Getting started
+
+This page starts a new API project from the package's `tsp init` template,
+then takes it from the spec to a running Hono route.
+
+## Start a project
+
+You need Node.js for `tsp`, and [Bun](https://bun.sh) on the PATH for the
+generator, `nxgt-openapi`, which runs on Bun
+([Compile and generate](#compile-and-generate)).
+
+Run `tsp init` with the template, in an empty directory:
+
+```sh
+mkdir petstore && cd petstore
+npx --package=@typespec/compiler tsp init https://unpkg.com/@nxgt/typespec/templates/scaffolding.json
+```
+
+`tsp init` asks for the template, the project's name and the emitters. To
+answer them on the command line instead:
+
+```sh
+npx --package=@typespec/compiler tsp init https://unpkg.com/@nxgt/typespec/templates/scaffolding.json \
+  --template nxgt -y --project-name petstore
+```
+
+`--package=@typespec/compiler` matters: in a directory without the compiler,
+a bare `npx tsp` runs `tsp`, an unrelated npm package. `bunx
+--package=@typespec/compiler tsp init …` works too.
+
+`tsp init` writes into the current directory, then runs `npm install`, so it
+needs the network. The template ships from 0.9.0 on; an older version, or no
+network, fails before anything is written
+([troubleshooting](../troubleshooting.md#init-template-invalid-json-unable-to-parse-scaffoldingjson-unexpected-token--is-not-valid-json)).
+
+## What it writes
+
+| File | What it holds |
+| --- | --- |
+| `package.json` | the compiler, `@typespec/http`, `@typespec/openapi`, `@typespec/openapi3`, `@nxgt/typespec` and `@nxgt/openapi-codegen`, at their latest versions |
+| `tspconfig.yaml` | the linter's recommended rules, and OpenAPI 3.1 written to `openapi/openapi.yaml` |
+| `main.tsp` | the service, marked with `@operationIds`, and a `Users` resource |
+| `openapi-codegen.config.ts` | the generator's input and output, with the Hono routes on |
+| `README.md` | the commands below, and the scripts to add |
+| `.gitignore` | `node_modules/`, and TypeSpec's default output |
+
+`tspconfig.yaml` turns the linter on and emits OpenAPI 3.1, which
+`@nxgt/openapi-codegen` reads (it refuses 3.0, the emitter's default):
+
+```yaml
+# tspconfig.yaml
+linter:
+  extends:
+    - "@nxgt/typespec/recommended"
+emit:
+  - "@typespec/openapi3"
+options:
+  "@typespec/openapi3":
+    emitter-output-dir: "{project-root}/openapi"
+    openapi-versions:
+      - 3.1.0
+    output-file: openapi.yaml
+```
+
+`main.tsp` declares the service in the namespace `Api`, titled after the
+project, and one resource with each convention in place: a paged, filtered and sorted
+list, and the error aliases of each verb.
+
+```tsp
+// main.tsp (excerpt)
+@service(#{ title: "petstore" })
+@operationIds
+namespace Api;
+
+model User {
+  @visibility(Lifecycle.Read)
+  id: uuid;
+
+  @minLength(1)
+  @maxLength(80)
+  name: string;
+
+  email: email;
+
+  ...Timestamps;
+}
+
+@route("/users")
+@tag("Users")
+interface Users {
+  @get
+  list(
+    ...UserFilters,
+    ...PageParameters,
+    ...SortParameters<"name" | "createdAt">,
+  ): Page<User> | ListErrors;
+
+  @get
+  get(@path id: uuid): User | GetErrors;
+
+  @post
+  create(@body user: Create<User>): {
+    @statusCode _: 201;
+    @body user: User;
+  } | CreateErrors;
+
+  @patch
+  update(@path id: uuid, @body user: MergePatchUpdate<User>): User | UpdateErrors;
+
+  @delete
+  delete(@path id: uuid): NoContentResponse | DeleteErrors;
+}
+```
+
+`@operationIds` names the operations `listUsers`, `getUser`, `createUser`,
+`updateUser` and `deleteUser` ([Operation ids](operation-ids.md)).
+
+```ts
+// openapi-codegen.config.ts
+import { defineConfig } from '@nxgt/openapi-codegen';
+
+export default defineConfig({
+	input: 'openapi/openapi.yaml',
+	output: 'src/generated',
+	hono: true,
+});
+```
+
+## Compile and generate
+
+Compile the spec to `openapi/openapi.yaml`, then generate the code from it.
+`nxgt-openapi` runs on Bun: it needs `bun` on the PATH, even through `npx` or
+an npm script, and fails with `env: 'bun': No such file or directory`
+without it ([troubleshooting](../troubleshooting.md#env-bun-no-such-file-or-directory)).
+`bunx nxgt-openapi generate` does the same as the `npx` line.
+
+```sh
+npx tsp compile .
+npx nxgt-openapi generate
+```
+
+```text
+openapi/openapi.yaml → src/generated: 5 written, 0 unchanged
+```
+
+`src/generated` then holds `types.ts`, `zod.ts`, `operations.ts`, `paths.ts`
+and `hono.ts`. The linter runs in `tsp compile`; the template's spec passes
+it.
+
+## Add the scripts
+
+`tsp init` writes its own `package.json`, so the template cannot add
+scripts. Add these two, so the code never lags the spec:
+
+```json
+{
+  "scripts": {
+    "api": "tsp compile . && nxgt-openapi generate",
+    "api:check": "tsp compile . && nxgt-openapi generate --check"
+  }
+}
+```
+
+`api:check` exits with 1 and lists the files when the generated code is out
+of date: run it in CI.
+
+## Serve it
+
+The generated `hono.ts` binds the routes to the spec through
+[`@nxgt/openapi-hono`](https://www.npmjs.com/package/@nxgt/openapi-hono).
+Install it, Hono, and zod, which the generated validators import, with the
+package manager `tsp init` used:
+
+```sh
+npm install @nxgt/openapi-hono hono zod
+```
+
+Then register a handler per operation. Each one reads its validated input,
+and may only answer the replies the spec declares:
+
+```ts
+// src/app.ts
+import { Hono } from 'hono';
+import { createRoutes } from './generated/hono';
+import type { NotFoundBody } from './generated/types';
+
+const app = new Hono();
+const routes = createRoutes(app);
+
+routes.operation('getUser', async (c) => {
+	const { id } = c.req.valid('param');
+	const user = await users.find(id);
+	if (!user) {
+		const body: NotFoundBody = {
+			status: 404,
+			message: 'errors.not-found',
+			timestamp: new Date().toISOString(),
+		};
+		return c.json(body, 404);
+	}
+	return c.json(user, 200);
+});
+
+routes.operation('listUsers', async (c) => {
+	const { name, page = 1, pageSize = 20, orderBy, direction } = c.req.valid('query');
+	return c.json(await users.page({ name, page, pageSize, orderBy, direction }), 200);
+});
+
+export default app;
+```
+
+`users` stands for your data layer. Annotate an error body with its generated
+type, as `NotFoundBody` above: an object literal passed straight to
+`c.json(…, 404)` is inferred beside the handler's other returns, its fields
+turn optional, and the handler fails with `TS2769: No overload matches this
+call`. A `418`,
+or a 404 without `timestamp`, does not compile either. More on the routes in the
+[`@nxgt/openapi-hono` README](https://www.npmjs.com/package/@nxgt/openapi-hono),
+and on serving a page in [Pagination](pagination.md#serving-it).
+
+## Rename the resource
+
+`Users` is an example. To make it your own resource, rename the model, its
+filters, the interface, the route and the tag in `main.tsp`, and the body
+parameters with them:
+
+```tsp
+model Pet {
+  @visibility(Lifecycle.Read)
+  id: uuid;
+
+  @minLength(1)
+  name: string;
+
+  ...Timestamps;
+}
+
+model PetFilters {
+  @query
+  name?: string;
+}
+
+@route("/pets")
+@tag("Pets")
+interface Pets {
+  @get
+  list(...PetFilters, ...PageParameters, ...SortParameters<"name" | "createdAt">): Page<Pet> | ListErrors;
+
+  @get
+  get(@path id: uuid): Pet | GetErrors;
+
+  @post
+  create(@body pet: Create<Pet>): {
+    @statusCode _: 201;
+    @body pet: Pet;
+  } | CreateErrors;
+
+  @patch
+  update(@path id: uuid, @body pet: MergePatchUpdate<Pet>): Pet | UpdateErrors;
+
+  @delete
+  delete(@path id: uuid): NoContentResponse | DeleteErrors;
+}
+```
+
+The operation names stay; `@operationIds` takes the resource from the
+interface, so the ids become `listPets`, `getPet`, `createPet`, `updatePet`
+and `deletePet`. Run `tsp compile .` and `nxgt-openapi generate` again, and
+the generated types, `Pet` and `PetPage`, follow. A name the singular rule
+does not know takes `@operationIds(#{ singular: "…" })` on the interface
+([Operation ids](operation-ids.md)).
+
+A second resource is a second model and interface, in the same namespace or
+in files of their own ([README](../README.md#a-spec-split-across-files)).
+
+Next: what each error alias holds, in [Error replies](errors.md), and the
+rules the linter checks, in [Linter](linter.md).

package/docs/roadmap.md

@@ -6,12 +6,7 @@ generated by `@nxgt/openapi-codegen` in CI before it ships.
 
 ## Now
 
-- **A linter.** The ruleset `@nxgt/typespec/recommended`, which a spec
-  extends in `tspconfig.yaml`, warns of a list that returns an array
-  (`list-returns-page`), a service without `@operationIds`
-  (`service-operation-ids`), and an error reply without the envelope
-  (`error-body-shape`). Each rule can be turned off, for the spec or for one
-  operation.
+Nothing in progress.
 
 ## Later
 
@@ -25,6 +20,22 @@ generated by `@nxgt/openapi-codegen` in CI before it ships.
 
 ## Shipped
 
+### 0.9.0
+
+- **A `tsp init` template.** `tsp init` with the package's template
+  starts a project with the conventions in place: `@operationIds`, a paged
+  resource with its error aliases, the linter on, and the OpenAPI that
+  `@nxgt/openapi-codegen` generates from.
+
+### 0.8.0
+
+- **A linter.** The ruleset `@nxgt/typespec/recommended`, which a spec
+  extends in `tspconfig.yaml`, warns of a list that returns an array
+  (`list-returns-page`), a service without `@operationIds`
+  (`service-operation-ids`), and an error reply without the envelope
+  (`error-body-shape`). Each rule can be turned off, for the spec or for one
+  operation.
+
 ### 0.7.0
 
 - **Error aliases by verb.** `ListErrors`, `GetErrors`, `CreateErrors`,

package/docs/troubleshooting.md

@@ -27,6 +27,67 @@ no `package.json` to resolve it from.
 devDependencies, with the command in the
 [README's Install section](../README.md#install).
 
+## `init-template-invalid-json: Unable to parse …/scaffolding.json: Unexpected token … is not valid JSON`
+
+**When:** `tsp init` with the package's template, before it writes anything.
+
+```text
+error init-template-invalid-json: Unable to parse https://unpkg.com/@nxgt/typespec@0.8.0/templates/scaffolding.json: Unexpected token 'N', "Not found:"... is not valid JSON. Check that the template URL is correct.
+```
+
+**Why:** the URL names no template, so unpkg answers a page of text, `Not
+found: …` or `Package version not found: …`, which `tsp init` cannot parse.
+The template ships from 0.9.0 on: a version before it in the URL, a version
+that is not published, or a typo in the path all answer that page.
+
+**Fix:** drop the version, or name 0.9.0 or later, and keep the path as it is:
+
+```sh
+npm view @nxgt/typespec version   # 0.9.0 or later
+npx --package=@typespec/compiler tsp init https://unpkg.com/@nxgt/typespec/templates/scaffolding.json
+```
+
+## `init-template-download-failed: Failed to download template from …: fetch failed`
+
+**When:** `tsp init` with the package's template, before it writes anything.
+
+```text
+error init-template-download-failed: Failed to download template from https://unpkg.com/@nxgt/typespec/templates/scaffolding.json: fetch failed. Check that the template URL is correct.
+```
+
+**Why:** `tsp init` could not reach the host: no network, a firewall or
+proxy in the way, or a host name mistyped. Nothing answered, unlike the entry
+above, where unpkg answers a page that is not the template.
+
+**Fix:** check that the host answers from that machine, then run `tsp init`
+again:
+
+```sh
+curl -fsSI https://unpkg.com/@nxgt/typespec/templates/scaffolding.json
+```
+
+## `env: 'bun': No such file or directory`
+
+**When:** `nxgt-openapi generate` runs, through `npx`, an npm script such as
+the template's `api`, or a CI step, on a machine without Bun. A shell in
+another locale quotes it `‘bun’`; macOS prints `env: bun: No such file or
+directory`. The exit code is 127.
+
+**Why:** `@nxgt/openapi-codegen`'s CLI, `nxgt-openapi`, runs on
+[Bun](https://bun.sh): its first line is `#!/usr/bin/env bun`. `npx` and
+`npm run` find the script, then the system looks for `bun` to run it.
+`tsp compile` runs on Node and is not affected.
+
+**Fix:** install Bun, and make sure `bun` is on the PATH of the shell or the
+CI job that runs the generator:
+
+```sh
+curl -fsSL https://bun.sh/install | bash
+bunx nxgt-openapi generate
+```
+
+In GitHub Actions, add `oven-sh/setup-bun@v2` before the step.
+
 ## `Duplicate type name: 'NotFoundBody'`
 
 **When:** `tsp compile` runs on a spec that declares its own model named like

package/lib/errors.tsp

@@ -130,6 +130,29 @@ model TooManyRequests {
   @body body: TooManyRequestsBody;
 }
 
+/**
+ * A request with this `Idempotency-Key` is still running. Retry it as it is,
+ * after `Retry-After`.
+ */
+@error
+model IdempotencyInProgress {
+  @statusCode _: 409;
+  ...RateLimitHeaders;
+  ...RetryAfterHeader;
+  @body body: ConflictBody;
+}
+
+/**
+ * This `Idempotency-Key` was already used for a request with another body. A
+ * new request takes a new key.
+ */
+@error
+model IdempotencyKeyReused {
+  @statusCode _: 422;
+  ...RateLimitHeaders;
+  @body body: UnprocessableEntityBody;
+}
+
 /**
  * The server failed. With `validateResponses`, `@nxgt/openapi-hono` answers
  * it too when a reply breaks the spec, with `errors.response-validation-failed`.

package/lib/headers.tsp

@@ -51,26 +51,3 @@ model RetryAfterHeader {
   @header("Retry-After")
   retryAfter?: integer;
 }
-
-/**
- * A request with this `Idempotency-Key` is still running. Retry it as it is,
- * after `Retry-After`.
- */
-@error
-model IdempotencyInProgress {
-  @statusCode _: 409;
-  ...RateLimitHeaders;
-  ...RetryAfterHeader;
-  @body body: ConflictBody;
-}
-
-/**
- * This `Idempotency-Key` was already used for a request with another body. A
- * new request takes a new key.
- */
-@error
-model IdempotencyKeyReused {
-  @statusCode _: 422;
-  ...RateLimitHeaders;
-  @body body: UnprocessableEntityBody;
-}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/typespec",
-	"version": "0.8.0",
+	"version": "0.9.1",
 	"license": "MIT",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -9,6 +9,7 @@
 	"files": [
 		"dist",
 		"lib",
+		"templates",
 		"docs",
 		"README.md",
 		"package.json",

package/templates/nxgt/README.md

@@ -0,0 +1,33 @@
+# {{name}}
+
+The API is written in TypeSpec, in `main.tsp`, with the
+[`@nxgt/typespec`](https://www.npmjs.com/package/@nxgt/typespec) conventions.
+
+Compile it to `openapi/openapi.yaml`, then generate the types, validators
+and routes into `src/generated`. The generator, `nxgt-openapi`, runs on
+[Bun](https://bun.sh): it needs `bun` on the PATH, even through `npx` or an
+npm script.
+
+```sh
+npx tsp compile .
+npx nxgt-openapi generate
+```
+
+Chain both in `package.json`, so the code never lags the spec:
+
+```json
+{
+  "scripts": {
+    "api": "tsp compile . && nxgt-openapi generate",
+    "api:check": "tsp compile . && nxgt-openapi generate --check"
+  }
+}
+```
+
+`tspconfig.yaml` turns on the linter's recommended rules, which warn of a
+list without a page, a service without `@operationIds`, and an error reply
+without the envelope.
+
+The next steps, serving the routes with Hono and renaming the `Users`
+resource, are in
+[Getting started](https://github.com/softistx/nxgt-http/blob/develop/packages/typespec/docs/guide/getting-started.md).

package/templates/nxgt/main.tsp

@@ -0,0 +1,68 @@
+// The API's spec. `tsp compile .` writes openapi/openapi.yaml, and
+// `nxgt-openapi generate` the types, validators and routes from it.
+import "@typespec/http";
+import "@nxgt/typespec";
+
+using Http;
+using Nxgt;
+
+/** The {{name}} API. */
+@service(#{ title: "{{name}}" })
+@operationIds
+namespace Api;
+
+/** Someone who uses the API. */
+model User {
+  @visibility(Lifecycle.Read)
+  id: uuid;
+
+  @minLength(1)
+  @maxLength(80)
+  name: string;
+
+  email: email;
+
+  ...Timestamps;
+}
+
+/** What the user list filters on. */
+model UserFilters {
+  /** Users of this name. */
+  @query
+  name?: string;
+}
+
+// Verbs @operationIds completes: list is listUsers, get is getUser.
+@route("/users")
+@tag("Users")
+interface Users {
+  /** One page of the users, filtered and sorted. */
+  @get
+  list(
+    ...UserFilters,
+    ...PageParameters,
+    ...SortParameters<"name" | "createdAt">,
+  ): Page<User> | ListErrors;
+
+  /** One user. */
+  @get
+  get(@path id: uuid): User | GetErrors;
+
+  /** Creates a user. */
+  @post
+  create(@body user: Create<User>): {
+    @statusCode _: 201;
+    @body user: User;
+  } | CreateErrors;
+
+  /** Updates a user with a merge patch. */
+  @patch
+  update(
+    @path id: uuid,
+    @body user: MergePatchUpdate<User>,
+  ): User | UpdateErrors;
+
+  /** Deletes a user. */
+  @delete
+  delete(@path id: uuid): NoContentResponse | DeleteErrors;
+}

package/templates/nxgt/openapi-codegen.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from '@nxgt/openapi-codegen';
+
+export default defineConfig({
+	input: 'openapi/openapi.yaml',
+	output: 'src/generated',
+	hono: true,
+});

package/templates/scaffolding.json

@@ -0,0 +1,37 @@
+{
+	"nxgt": {
+		"title": "nxgt REST API",
+		"description": "A REST API with the @nxgt conventions: ids as written, pages, the error envelope and the linter, generated with @nxgt/openapi-codegen.",
+		"compilerVersion": "1.16.0",
+		"libraries": [
+			"@typespec/http",
+			"@typespec/openapi",
+			"@nxgt/typespec",
+			"@nxgt/openapi-codegen"
+		],
+		"config": {
+			"linter": {
+				"extends": ["@nxgt/typespec/recommended"]
+			}
+		},
+		"emitters": {
+			"@typespec/openapi3": {
+				"selected": true,
+				"label": "OpenAPI 3.1 document",
+				"options": {
+					"emitter-output-dir": "{project-root}/openapi",
+					"openapi-versions": ["3.1.0"],
+					"output-file": "openapi.yaml"
+				}
+			}
+		},
+		"files": [
+			{ "path": "nxgt/main.tsp", "destination": "main.tsp" },
+			{
+				"path": "nxgt/openapi-codegen.config.ts",
+				"destination": "openapi-codegen.config.ts"
+			},
+			{ "path": "nxgt/README.md", "destination": "README.md" }
+		]
+	}
+}