@portpowered/reference-data 0.4.1 → 0.4.2

package/README.md

@@ -12,17 +12,41 @@ last modified: 2026, october, 7
 Canonical inputs in the application repository are `docs/user-guides/`, `api/ci/`, `api/openapi-main.yaml` and its modular references. `api/cif/` and `api/openapi.yaml` are bundled projections. Generation reuses the existing capability normalizer, preserving the application's generated catalog contract. Install the website dependencies before generating this package.
 
 1. Change the canonical reference resources.
-2. Run `npm run reference:generate` from `website/`.
+2. Record the input snapshot with `node packages/reference-data/scripts/source-provenance.mjs --record <full-commit>` from the repository root, then run `npm run reference:generate` from `website/`.
 3. Run `npm run reference:check` to verify generated data. The website production build also runs this check.
 
 The documentation package omits generated descriptions beginning with `Schema for`, while preserving useful field descriptions and all validation properties. `descriptions.json` supplies capability introductions independently of validation rules. Edit it for concise customer-facing copy, then regenerate.
 
 Never edit generated JSON manually. Regeneration removes obsolete resources when capabilities or members are removed or renamed.
 
+The manifest records the canonical input snapshot's `sourceCommit`, aggregate `sourceInputSHA256`, input count and state. Input hashing normalizes text to LF and does not publish internal source filenames. Local development can record inputs modified from the base commit; publication requires `sourceInputState: committed`. After committing canonical changes, record that commit and regenerate before preparing the public tag. This keeps ordinary builds possible before publication and avoids embedding a self-referential release commit. Default-version aliases explicitly record `aliasOf` and have exactly the canonical file's bytes; Markdown `links` describe navigation relationships.
+
+## Private REST contracts
+
+For future internal REST endpoints, put the boolean extension `x-internal: true` on the canonical OpenAPI path item or individual operation. Annotate internal component schemas (or individual properties) the same way. An omitted annotation or `x-internal: false` retains the current public behavior. A private path hides all its operations; a private operation leaves its public siblings available.
+
+Generation parses the bundled YAML with `js-yaml` and applies one structured public projection before producing the JSON export, raw OpenAPI YAML, operation guides and authorization inventories. The website and backend public assets consume this projection, and the legacy website `/docs/agents/api.md` overview uses the same filter. Canonical contracts remain available to internal code generation. This annotation controls documentation publication; runtime authentication and authorization still apply independently.
+
+Public references to removed components, including discriminator mappings and security requirements, fail generation. Move the reference behind an internal operation or provide a separate public schema; do not publish a dangling reference. Literal examples are customer data, not annotation containers. `npm run reference:check` runs exclusion and reference-integrity tests and checks generated bytes before a website release. The raw YAML is serialized from the same filtered document, with a regression checking the parsed exported bytes directly.
+
 ## Consuming the package
 
+Internal website builds (`npm run build`) resolve the checked-in generated exports through the source build entry point. They validate generation without requiring an npm publication or publishing credentials. Backend development uses the local Go workspace module. Public dependencies can be downloaded anonymously.
+
+Website release builds (`npm run build:release`, including the pilot Docker image) resolve the exact registry pin and require its manifest to equal the checked-in projection. Backend release images download the pinned public Go tag and check the same manifest. Neither consumer build publishes packages.
+
+## Automated publication
+
+The public data repository owns `.github/workflows/npm-publish.yml`; its source template lives in `release/npm-publish.yml` here. It validates immutable `vX.Y.Z` tags, public asset hashes and Go embeds before publishing under the `next` npm tag. Ordinary application CI has no publishing permission.
+
+Configure a trusted publisher once in [npm package settings](https://www.npmjs.com/package/@portpowered/reference-data/access): provider **GitHub Actions**, organization **portpowered**, repository **portos-reference-data**, workflow filename **npm-publish.yml**, no environment name, and allow direct publishing. The workflow requests `id-token: write`; npm exchanges that short-lived GitHub OIDC identity for publication authority. No user OAuth refresh grant, stored npm token or per-release security-key approval is required. Setup itself may require the package owner's security-key verification. See [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/).
+
+Commit the public data projection and push its immutable Go tag to release. Manual dispatch accepts an existing tag for retrying a failed publication; published versions cannot be replaced. Confirm both registry availability and Go module retrieval before updating consumer pins.
+
 Import `@portpowered/reference-data/capabilities`, `@portpowered/reference-data/openapi` or `@portpowered/reference-data/guides` with your runtime's JSON import mechanism. The release repository contains public projections only. Authored application sources stay in the private application repository. Release the same version to npm and the public Go module `github.com/portpowered/portos-reference-data`; the manifest lists identical file hashes for both distributions.
 
 Individual schemas are exported as `@portpowered/reference-data/resources/<capability>/configuration.json`, `state-<attribute>.json`, and `message-<name>.json`. Consumers can render field tables directly from these resources. Keep the package imports on the server or at build time to avoid shipping the complete catalog in browser JavaScript.
 
+REST operation guides link directly to `/docs/references/schemas/<name>.json`, `/docs/references/parameters/<name>.json` and `/docs/references/headers/<name>.json`. Schema files use JSON Schema draft-07 with OpenAPI nullability and exclusive bounds converted; parameter/header files retain their OpenAPI definitions. References and discriminator mappings point to the same public host. `/docs/for-ai/schemas.md` and `/docs/references/schemas/index.json` index these files. Agents can retrieve the components needed for one operation without reading the full OpenAPI bundle. Generation checks compile the complete linked schema graph and validate the API's complete request/response examples through it.
+
 Run `npm pack` in this directory to produce a portable bundle. The bundle contains generated JSON, the raw public tree and this README; regeneration belongs to the source repository. The Go module embeds that public tree and exposes it through `Files() fs.FS`. Public URLs are rooted at `/llms.txt`, `/docs/for-ai/` and `/docs/references/`; missing files are absent rather than an app-shell fallback. Run `node scripts/validate-public-assets.mjs` and `go test ./...` before release.