@opensoftware/contracts 2.0.0 → 2.1.0

package/README.md

@@ -91,18 +91,41 @@ the workflow by hand with the tag. The CONTRACT check and `osf-contracts breakin
 Only the TypeScript package exists (ADR 0012). A client for another language can be generated from
 `openapi/openapi.json` with any OpenAPI generator when someone needs one.
 
+A new package gets its publish workflow and its release-please entries with `osf release-files`; the check RELEASE
+fails until they are current, and also when a workflow differs from `tools/scaffold/publish-workflow.yml`.
+
 One-time setup (no credential is ever stored in the repository):
 
 1. npm: the organization `opensoftware` owns the scope `@opensoftware`, under which every package of this
    repository is published.
 2. GitHub: the publish job runs in the environment `npm` (Settings → Environments; GitHub creates it on the first
    run).
-3. First version only: npm configures trusted publishing per existing package, so `1.0.0` needs a token. Add a
-   granular npm access token with read and write access to the `opensoftware` organization's packages as the
-   secret `NPM_TOKEN` (a repository secret or a secret of the environment `npm`), or publish `1.0.0` by hand.
-4. After the first version: on npmjs.com, package settings → Trusted publishing, add GitHub Actions with the
-   repository `sesigl/open-software-factory`, the workflow `publish-contracts.yml` and the environment `npm`.
-   Then delete the secret `NPM_TOKEN` and revoke the token. Later versions publish through OIDC only.
+3. First version only: npm adds a trusted publisher only to a package that exists, so a maintainer publishes the
+   first version by hand, from the release tag, with their own npm login and two-factor authentication:
+   `pnpm --filter "<package>..." build`, `pnpm --dir <folder> pack`, then `npm publish <file>.tgz --access public`.
+4. Then add the trusted publisher, on npmjs.com (package settings → Trusted publishing) or with
+   `npm trust github <package> --file publish-<name>.yml --repository sesigl/open-software-factory --environment npm
+   --allow-publish --allow-stage-publish`. Every later version publishes through OIDC only, with a provenance
+   statement; the repository holds no npm token.
+
+An agent can do step 4 and the checks below with the npm CLI (11.19 or later). It needs a maintainer's
+`npm login --registry https://registry.npmjs.org`. Every `npm trust` call needs two-factor authentication, also
+`list`. Without a terminal, the call fails with `EOTP` and prints an `authUrl` and a `doneUrl`. The maintainer
+opens the `authUrl` and approves. Then a `GET` of the `doneUrl`, with the login's token as a bearer token, returns
+a `token`. The agent passes it as `--otp=<token>` to the next `npm trust` calls; it stays valid for some minutes.
+
+To check all packages, run `npm trust list <package>` for each `publish-*.yml` that publishes to npm. Each package
+has exactly one entry: this repository, its own workflow file, the environment `npm`, and the permissions
+`createPackage` and `createStagedPackage`.
+
+When a publish fails with `E404 Not Found - PUT https://registry.npmjs.org/@opensoftware%2f<name>`:
+
+- npm did not accept the job as a trusted publisher. Check that the job has `id-token: write` and
+  `environment: npm`, and compare the package's entry with the rule above.
+- An entry can look correct and still fail. Then remove it with `npm trust revoke <package> --id=<id>`, add it
+  again with step 4 and run the workflow again with the tag.
+- After a successful publish, npm can take some minutes before the version is available. A build that installs
+  the new version in this time fails with `ETARGET`; run it again.
 
 ## Configuration
 

package/openapi/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Open Software Factory contracts",
-    "version": "2.0.0",
+    "version": "2.1.0",
     "description": "The shared formats as named models, and the HTTP APIs of the modules. Generated by `pnpm build` in contracts/ from typespec/. Do not edit.",
     "license": {
       "name": "Apache-2.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensoftware/contracts",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "The shared formats of the open software factory: JSON Schemas, TypeScript types and the osf-contracts CLI.",
   "license": "Apache-2.0",
   "repository": {
@@ -44,7 +44,7 @@
     "@typespec/openapi": "1.17.0",
     "@typespec/openapi3": "1.17.0",
     "openapi-typescript": "7.13.0",
-    "@opensoftware/testkit": "0.28.0"
+    "@opensoftware/testkit": "0.30.0"
   },
   "scripts": {
     "build": "node scripts/build.ts",