openapi-versions 0.0.0 → 0.1.0

package/README.md

@@ -17,9 +17,9 @@ mise install && pnpm install
 # (use --require-gate or "gate": "required" in CI): https://github.com/oasdiff/oasdiff/releases
 pnpm codegen         # check + merge + generate for playground/ and test/fixtures/ (output is gitignored)
 pnpm typecheck       # includes compile-time guarantees in test/types.check.ts
-npm test                # 34 tests: merge, since maps, oasdiff gate, compat matrix, React, loaders, major transition
+pnpm test           # 41 tests: merge, since maps, oasdiff gate, compat matrix, React, loaders, major transition
 pnpm playground:api  # one client build vs backends 1.2.0 … 2.0.0
-npx tsx codegen/cli.ts --check-only --config test/fixtures/broken.config.json   # shows the CI gate failing
+pnpm exec tsx codegen/cli.ts --check-only --config test/fixtures/broken.config.json   # shows the CI gate failing
 ```
 
 ## How it works

package/docs/adr/0008-prereleases-via-snapshots.md

@@ -0,0 +1,16 @@
+# 0008. Prereleases via on-demand snapshots
+
+- Status: accepted
+- Date: 2026-11-02
+
+## Context
+
+The repo is trunk-based on `main` and releases when the Version Packages PR is merged (npm trusted publishing, no token). Consumers sometimes need unreleased changes. Changesets offers pre mode (`x.y.z-rc.n`, state in `.changeset/pre.json`) and snapshots (`x.y.z-next-<timestamp>`). Pre mode on `main` turns every Version Packages PR into a prerelease and blocks stable hotfixes; a long-lived `next` branch means two integration branches to keep in sync.
+
+## Decision
+
+Stay trunk-based. Prereleases are snapshots published by running the Release workflow manually (`workflow_dispatch`, `main` only) with `changeset version --snapshot next` and `changeset publish --tag next --no-git-tag`. `snapshot.useCalculatedVersion` makes the version read `0.2.0-next-…`. The job fails when no changesets are pending. The `latest` tag is never touched. No automatic snapshot on push.
+
+## Consequences
+
+No extra branch, no `pre.json`, stable releases are never blocked. Snapshot versions are timestamped, not a tidy `rc.1`, `rc.2` sequence, and each one stays on npm. Revisit automatic snapshots on push once a downstream app consumes `@next`, and pre mode on `main` only for a short stabilization window before a major.

package/docs/adr/README.md

@@ -11,3 +11,4 @@ One file per decision, `NNNN-title.md`, [MADR](https://adr.github.io/madr/) styl
 | [0005](0005-patch-openapi-typescript-helpers.md) | Patch `openapi-typescript-helpers` until upstream ships the fix | accepted |
 | [0006](0006-tooling-mise-pnpm-biome.md) | mise, pnpm, Biome, Vitest, Changesets, Renovate; no turbo yet | accepted |
 | [0007](0007-mit-license.md) | MIT license | accepted |
+| [0008](0008-prereleases-via-snapshots.md) | Prereleases are on-demand snapshots from `main` under the `next` tag | accepted |

package/docs/how-to.md

@@ -1,6 +1,6 @@
 # How-to
 
-Each recipe lists the exact steps. Run `pnpm codegen`, `pnpm typecheck` and `npm test` after changes.
+Each recipe lists the exact steps. Run `pnpm codegen`, `pnpm typecheck` and `pnpm test` after changes.
 - [Add the spec of a new backend release](#add-the-spec-of-a-new-backend-release)
 - [Use a feature before the backend ships it](#use-a-feature-before-the-backend-ships-it)
 - [Gate a query, a mutation, a field](#gate-a-query-a-mutation-a-field)
@@ -146,10 +146,10 @@ oasdiff breaking specs/1.6.0.json new-spec.json --fail-on ERR
 Client CI:
 
 ```bash
-npm ci
+pnpm install --frozen-lockfile
 pnpm codegen        # fails on a breaking pair, bad config, or missing floor spec
 git diff --exit-code src/generated   # if generated code is committed
-pnpm typecheck && npm test
+pnpm typecheck && pnpm test
 ```
 
 `pnpm check:breaking` runs only the gate and writes nothing.

package/package.json

@@ -1,24 +1,7 @@
 {
   "name": "openapi-versions",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "description": "Multi-version OpenAPI client for the openapi-ts ecosystem: merges the minor specs of one API major, generates tolerant types with openapi-typescript, and gates features at runtime.",
-  "scripts": {
-    "codegen:playground": "rm -rf playground/generated && tsx codegen/cli.ts --config playground/openapi-versions.config.json",
-    "codegen:test": "rm -rf test/fixtures/generated && tsx codegen/cli.ts --config test/fixtures/openapi-versions.config.json",
-    "codegen": "npm run codegen:playground && npm run codegen:test",
-    "check:breaking": "tsx codegen/cli.ts --check-only --config playground/openapi-versions.config.json",
-    "typecheck": "npm run codegen:test && npm run codegen:playground && tsc --noEmit",
-    "test": "npm run codegen:test && vitest run",
-    "playground": "npm run codegen:playground && vite --config playground/app/vite.config.ts",
-    "playground:api": "npm run codegen:playground && tsx playground/api/run.ts",
-    "build:playground": "npm run codegen:playground && vite build --config playground/app/vite.config.ts",
-    "build": "tsup",
-    "prepack": "npm run build",
-    "lint": "biome check .",
-    "format": "biome check --write .",
-    "changeset": "changeset",
-    "release": "pnpm build && changeset publish"
-  },
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -109,8 +92,23 @@
       "optional": true
     }
   },
-  "packageManager": "pnpm@12.3.4",
   "engines": {
     "node": ">=20"
+  },
+  "scripts": {
+    "codegen:playground": "rm -rf playground/generated && tsx codegen/cli.ts --config playground/openapi-versions.config.json",
+    "codegen:test": "rm -rf test/fixtures/generated && tsx codegen/cli.ts --config test/fixtures/openapi-versions.config.json",
+    "codegen": "pnpm codegen:playground && pnpm codegen:test",
+    "check:breaking": "tsx codegen/cli.ts --check-only --config playground/openapi-versions.config.json",
+    "typecheck": "pnpm codegen:test && pnpm codegen:playground && tsc --noEmit",
+    "test": "pnpm codegen:test && vitest run",
+    "playground": "pnpm codegen:playground && vite --config playground/app/vite.config.ts",
+    "playground:api": "pnpm codegen:playground && tsx playground/api/run.ts",
+    "build:playground": "pnpm codegen:playground && vite build --config playground/app/vite.config.ts",
+    "build": "tsup",
+    "lint": "biome check .",
+    "format": "biome check --write .",
+    "changeset": "changeset",
+    "release": "pnpm build && changeset publish"
   }
-}
+}

package/skills/openapi-versions-add-spec/SKILL.md

@@ -34,4 +34,4 @@ Backend serves `/api/vN+1` side by side with the frozen `/api/vN` (with `Sunset`
 
 ## Verify
 
-`pnpm codegen && pnpm typecheck && npm test`. Report what changed in `meta.ts`.
+`pnpm codegen && pnpm typecheck && pnpm test`. Report what changed in `meta.ts`.

package/skills/openapi-versions-setup/SKILL.md

@@ -17,10 +17,10 @@ Read `docs/concepts.md` once if the vocabulary (major, minor, floor, gated) is u
    ```
    The floor is the oldest minor the app supports and must have its own spec file. Ask the user for the floor if unknown (default suggestion: the oldest minor running in any environment: prod, staging, on-prem).
 4. **Generate**: `npx openapi-versions` (or an npm script). Expect `ok v1: a -> b` lines then `gen v1: …`.
-5. **Install**: `npm i openapi-versions openapi-fetch openapi-react-query @tanstack/react-query` and `npm i -D openapi-typescript "typescript@<7"`; apply the `openapi-typescript-helpers` patch from `patches/` (patch-package).
+5. **Install**: with the app's package manager (`npm i`, `pnpm add`, `yarn add`): runtime `openapi-versions openapi-fetch openapi-react-query @tanstack/react-query`, dev `openapi-typescript "typescript@<7"`; apply the `openapi-typescript-helpers` patch from `patches/` (patch-package).
    Import everything from the generated `<outDir>/v<n>/client.ts` (`ApiVersionProvider`, `useApi`, `Feature`, `createApi`, `Paths`); the major appears only in that import path.
 6. **Provider**: wrap the app in `QueryClientProvider` then `<ApiVersionProvider baseUrl="https://host/api/v<n>">`. The base URL must include the major prefix; `/version` is read relative to it.
-7. **Verify**: `pnpm typecheck && npm test`; for a visual check `pnpm playground`.
+7. **Verify**: `pnpm typecheck && pnpm test`; for a visual check `pnpm playground`.
 
 ## Backend prerequisites (confirm, do not assume)