📦🔧：get the first release ready to publish

README.md

@@ -5,6 +5,8 @@ development: type guards, argument validation, structured errors, and terminal
 text.
 
 They are published separately, versioned together, and depend on almost nothing.
+The API reference for all of them is on the
+[OpenINF portal](https://open.inf.is/docs/sdk/).
 
 ## Why another utility suite
 
@@ -155,7 +157,11 @@ TypeScript consumers want `moduleResolution` set to `node16`, `nodenext`, or
 
 ## Documentation
 
-API documentation is generated with [TypeDoc](https://typedoc.org):
+The API reference for every package is published on the
+[OpenINF portal](https://open.inf.is/docs/sdk/), with one reference per release,
+so the pages match the version you installed.
+
+It is generated here with [TypeDoc](https://typedoc.org):
 
 ```console
 pnpm install

RELEASING.md

@@ -190,36 +190,58 @@ Two constraints make the first release different from every later one:
 - **A package must already exist on npm before you can configure it.** There's
   no way to pre-authorize a name that has never been published.
 
-`@openinf/util-core`, `@openinf/util`, `@openinf/assert`, `@openinf/util-array`,
-`@openinf/util-number`, `@openinf/util-date`, and `@openinf/util-string` have
-never been published. So, once:
+So a package that has never been published goes through one release by hand, and
+it has to be the release itself rather than whatever version `main` currently
+carries. Published from `main` before the "Version packages" PR has merged, a
+new package would go out at the version `main` carries for it, with its
+`workspace:*` dependencies pinned to the versions `main` carries for them, which
+for an already-published dependency is an old release that predates this code.
 
-1. Publish those seven manually, authenticated locally with an npm account that
-   can create packages under the `@openinf` scope:
+Once, for the release that first includes a new package:
+
+1. For each package that **is** already on npm, add a trusted publisher now (see
+   step 4 for the settings). These can be set up before anything else.
+
+2. Run **Release** and merge the "Version packages" PR it opens, as usual.
+
+3. From an up-to-date `main`, publish only the new packages, authenticated
+   locally with an npm account that can create packages under the `@openinf`
+   scope. Name each one with `--filter`; pnpm publishes them in dependency
+   order:
 
    ```bash
+   git pull
+   pnpm install --frozen-lockfile
    pnpm run build
-   pnpm --filter @openinf/util-core --filter @openinf/util \
-        --filter @openinf/assert --filter @openinf/util-array \
-        --filter @openinf/util-number --filter @openinf/util-date \
-        --filter @openinf/util-string publish
+   pnpm --filter @openinf/<new-package> --filter @openinf/<another> \
+        publish --no-git-checks
    ```
 
+   Leave out `--provenance`: it needs the CI's OIDC token and fails on a laptop,
+   so these first versions are the only ones without an attestation.
    `publishConfig.access` is set to `public` in each `package.json`, so no
-   `--access` flag is needed — without it npm would reject a scoped package as
+   `--access` flag is needed; without it npm would reject a scoped package as
    private.
 
-2. For **each** of the thirteen packages, on npmjs.com → package → Settings →
-   add a trusted publisher:
-   - Organization/user: the GitHub owner of this repo
-   - Repository: this repo
-   - Workflow filename: `release.yml` — just the filename, **not** the full
+4. For each package you just published, on npmjs.com → package → Settings → add
+   a trusted publisher:
+   - Publisher: GitHub Actions
+   - Organization or user: `OpenINF`
+   - Repository: `sdk`
+   - Workflow filename: `release.yml`, just the filename and **not** the full
      `.github/workflows/release.yml` path, which is a common cause of an E404
      that looks like a missing package rather than an auth failure
+   - Environment name: leave it empty; the release job does not run in a GitHub
+     environment, and a name the job does not declare makes the token exchange
+     fail
 
-3. Confirm no `NPM_TOKEN` secret remains configured for the repo. If one exists,
+5. Confirm no `NPM_TOKEN` secret remains configured for the repo. If one exists,
    it may take precedence over OIDC and defeat the point.
 
+6. Run **Release** again. With no changesets pending, it publishes the packages
+   whose new version is not on the registry yet, which is every package except
+   the ones from step 3.
+
 After that, both steps run from the Actions tab and no npm credentials live in
 CI.
 
@@ -262,6 +284,7 @@ to `src/` at runtime — `main`, `types`, and `exports` all point into `dist/`.
 - **Prerelease mode** (`changeset pre enter next`) exists for shipping a
   `3.1.0-next.0` line, but it's easy to get wrong — do it on a dedicated branch,
   never on `main`, or it blocks every other merge until you exit.
-- **pnpm's version is pinned** to 11.7.0 in both workflows. If you bump it, bump
-  it in both, and note that pnpm had an OIDC publishing regression in the 11.0.x
-  line — verify a publish still works after upgrading.
+- **pnpm's version is pinned** in both workflows and in the root
+  `package.json`'s `devEngines`. If you bump it, bump all three, and note that
+  pnpm had an OIDC publishing regression in the 11.0.x line — verify a publish
+  still works after upgrading.

packages/assert/README.md

@@ -23,3 +23,8 @@ assert(port > 0, 'PORT must be positive');
 // Both narrow, so `port` is a number from here on.
 port.toFixed();
 ```
+
+## Documentation
+
+The API reference for `@openinf/assert` and the other OpenINF packages is on the
+[OpenINF portal](https://open.inf.is/docs/sdk/), one version per release.

packages/assert/package.json

@@ -34,6 +34,7 @@
     "test:coverage": "node --experimental-test-module-mocks --experimental-test-coverage --test-coverage-include='test-dist/src/**' --test 'test-dist/test/**/*.js'",
     "prepublishOnly": "npm run clean && npm run build"
   },
+  "homepage": "https://open.inf.is/docs/sdk/",
   "repository": {
     "type": "git",
     "url": "https://github.com/OpenINF/sdk.git",

packages/gh-file-importer/README.md

@@ -63,3 +63,9 @@ const log: Logger = {
 
 const ghFileImporter = new GhFileImporter({ destDir: './tmp', log });
 ```
+
+## Documentation
+
+The API reference for `@openinf/gh-file-importer` and the other OpenINF packages
+is on the [OpenINF portal](https://open.inf.is/docs/sdk/), one version per
+release.

packages/gh-file-importer/package.json

@@ -34,6 +34,7 @@
     "test:coverage": "node --experimental-test-module-mocks --experimental-test-coverage --test-coverage-include='test-dist/src/**' --test 'test-dist/test/**/*.js'",
     "prepublishOnly": "npm run clean && npm run build"
   },
+  "homepage": "https://open.inf.is/docs/sdk/",
   "repository": {
     "type": "git",
     "url": "https://github.com/OpenINF/sdk.git",

packages/util-array/README.md

@@ -19,3 +19,8 @@ import { arraysEqual, toArray } from '@openinf/util-array';
 toArray(1); // ↪ [1]
 arraysEqual([1, 2], [1, 2]); // ↪ true
 ```
+
+## Documentation
+
+The API reference for `@openinf/util-array` and the other OpenINF packages is on
+the [OpenINF portal](https://open.inf.is/docs/sdk/), one version per release.

packages/util-array/package.json

@@ -34,6 +34,7 @@
     "test:coverage": "node --experimental-test-module-mocks --experimental-test-coverage --test-coverage-include='test-dist/src/**' --test 'test-dist/test/**/*.js'",
     "prepublishOnly": "npm run clean && npm run build"
   },
+  "homepage": "https://open.inf.is/docs/sdk/",
   "repository": {
     "type": "git",
     "url": "https://github.com/OpenINF/sdk.git",

packages/util-core/README.md

@@ -49,3 +49,8 @@ free of dependencies: nothing here needs anything more specific than itself.
 Most consumers should reach for
 [`@openinf/util`](https://www.npmjs.com/package/@openinf/util), which re-exports
 everything here alongside its full set of type guards.
+
+## Documentation
+
+The API reference for `@openinf/util-core` and the other OpenINF packages is on
+the [OpenINF portal](https://open.inf.is/docs/sdk/), one version per release.

packages/util-core/package.json

@@ -34,6 +34,7 @@
     "test:coverage": "node --experimental-test-module-mocks --experimental-test-coverage --test-coverage-include='test-dist/src/**' --test 'test-dist/test/**/*.js'",
     "prepublishOnly": "npm run clean && npm run build"
   },
+  "homepage": "https://open.inf.is/docs/sdk/",
   "repository": {
     "type": "git",
     "url": "https://github.com/OpenINF/sdk.git",

packages/util-date/README.md

@@ -39,3 +39,8 @@ isValidDate(new Date('nope')); // ↪ false
 isDate({ [Symbol.toStringTag]: 'Date' }); // ↪ false
 isTemporalInstant(new Date()); // ↪ false
 ```
+
+## Documentation
+
+The API reference for `@openinf/util-date` and the other OpenINF packages is on
+the [OpenINF portal](https://open.inf.is/docs/sdk/), one version per release.

packages/util-date/package.json

@@ -34,6 +34,7 @@
     "test:coverage": "node --experimental-test-module-mocks --experimental-test-coverage --test-coverage-include='test-dist/src/**' --test 'test-dist/test/**/*.js'",
     "prepublishOnly": "npm run clean && npm run build"
   },
+  "homepage": "https://open.inf.is/docs/sdk/",
   "repository": {
     "type": "git",
     "url": "https://github.com/OpenINF/sdk.git",

packages/util-errors/README.md

@@ -29,3 +29,8 @@ try {
   (error as MissingOptionError).code; // ↪ 'ERR_MISSING_OPTION'
 }
 ```
+
+## Documentation
+
+The API reference for `@openinf/util-errors` and the other OpenINF packages is
+on the [OpenINF portal](https://open.inf.is/docs/sdk/), one version per release.

packages/util-errors/package.json

@@ -34,6 +34,7 @@
     "test:coverage": "node --experimental-test-module-mocks --experimental-test-coverage --test-coverage-include='test-dist/src/**' --test 'test-dist/test/**/*.js'",
     "prepublishOnly": "npm run clean && npm run build"
   },
+  "homepage": "https://open.inf.is/docs/sdk/",
   "repository": {
     "type": "git",
     "url": "https://github.com/OpenINF/sdk.git",

packages/util-md-table/README.md

@@ -30,3 +30,8 @@ console.log(mdTbl2json(table, (value) => value.toLowerCase()));
   { col1: 'fee', col2: 'fie', col3: 'foe', col4: 'fum' }
 ]
 ```
+
+## Documentation
+
+The API reference for `@openinf/util-md-table` and the other OpenINF packages is
+on the [OpenINF portal](https://open.inf.is/docs/sdk/), one version per release.

packages/util-md-table/package.json

@@ -34,6 +34,7 @@
     "test:coverage": "node --experimental-test-module-mocks --experimental-test-coverage --test-coverage-include='test-dist/src/**' --test 'test-dist/test/**/*.js'",
     "prepublishOnly": "npm run clean && npm run build"
   },
+  "homepage": "https://open.inf.is/docs/sdk/",
   "repository": {
     "type": "git",
     "url": "https://github.com/OpenINF/sdk.git",

packages/util-number/README.md

@@ -31,3 +31,8 @@ isInteger(4); // ↪ true
 isInteger(4.5); // ↪ false
 isUint32(-1); // ↪ false
 ```
+
+## Documentation
+
+The API reference for `@openinf/util-number` and the other OpenINF packages is
+on the [OpenINF portal](https://open.inf.is/docs/sdk/), one version per release.

packages/util-number/package.json

@@ -34,6 +34,7 @@
     "test:coverage": "node --experimental-test-module-mocks --experimental-test-coverage --test-coverage-include='test-dist/src/**' --test 'test-dist/test/**/*.js'",
     "prepublishOnly": "npm run clean && npm run build"
   },
+  "homepage": "https://open.inf.is/docs/sdk/",
   "repository": {
     "type": "git",
     "url": "https://github.com/OpenINF/sdk.git",

packages/util-object/README.md

@@ -29,3 +29,8 @@ if (hasOwn(value, 'id')) {
   value.id; // ↪ narrowed to `unknown`, no cast needed
 }
 ```
+
+## Documentation
+
+The API reference for `@openinf/util-object` and the other OpenINF packages is
+on the [OpenINF portal](https://open.inf.is/docs/sdk/), one version per release.

packages/util-object/package.json

@@ -34,6 +34,7 @@
     "test:coverage": "node --experimental-test-module-mocks --experimental-test-coverage --test-coverage-include='test-dist/src/**' --test 'test-dist/test/**/*.js'",
     "prepublishOnly": "npm run clean && npm run build"
   },
+  "homepage": "https://open.inf.is/docs/sdk/",
   "repository": {
     "type": "git",
     "url": "https://github.com/OpenINF/sdk.git",

packages/util-string/README.md

@@ -29,3 +29,8 @@ isRegExp({ [Symbol.toStringTag]: 'RegExp' }); // ↪ false
 const mentionsNode = isStringContaining('Node');
 mentionsNode('Node.js'); // ↪ true
 ```
+
+## Documentation
+
+The API reference for `@openinf/util-string` and the other OpenINF packages is
+on the [OpenINF portal](https://open.inf.is/docs/sdk/), one version per release.

packages/util-string/package.json

@@ -34,6 +34,7 @@
     "test:coverage": "node --experimental-test-module-mocks --experimental-test-coverage --test-coverage-include='test-dist/src/**' --test 'test-dist/test/**/*.js'",
     "prepublishOnly": "npm run clean && npm run build"
   },
+  "homepage": "https://open.inf.is/docs/sdk/",
   "repository": {
     "type": "git",
     "url": "https://github.com/OpenINF/sdk.git",

packages/util-text/README.md

@@ -20,3 +20,8 @@ import { blueify, ellipsify } from '@openinf/util-text';
 
 console.log(blueify(ellipsify('Deserializing database tables')));
 ```
+
+## Documentation
+
+The API reference for `@openinf/util-text` and the other OpenINF packages is on
+the [OpenINF portal](https://open.inf.is/docs/sdk/), one version per release.

packages/util-text/package.json

@@ -34,6 +34,7 @@
     "test:coverage": "node --experimental-test-module-mocks --experimental-test-coverage --test-coverage-include='test-dist/src/**' --test 'test-dist/test/**/*.js'",
     "prepublishOnly": "npm run clean && npm run build"
   },
+  "homepage": "https://open.inf.is/docs/sdk/",
   "repository": {
     "type": "git",
     "url": "https://github.com/OpenINF/sdk.git",

packages/util-types/README.md

@@ -110,3 +110,8 @@ WebAssembly does not supply the missing reflection privilege:
 Passing a JavaScript object through `externref` does not expose its engine
 slots. A WebAssembly wrapper would still need a host-provided brand-check
 function.
+
+## Documentation
+
+The API reference for `@openinf/util-types` and the other OpenINF packages is on
+the [OpenINF portal](https://open.inf.is/docs/sdk/), one version per release.

packages/util-types/package.json

@@ -34,6 +34,7 @@
     "test:coverage": "node --experimental-test-module-mocks --experimental-test-coverage --test-coverage-include='test-dist/src/**' --test 'test-dist/test/**/*.js'",
     "prepublishOnly": "npm run clean && npm run build"
   },
+  "homepage": "https://open.inf.is/docs/sdk/",
   "repository": {
     "type": "git",
     "url": "https://github.com/OpenINF/sdk.git",

packages/util/README.md

@@ -61,3 +61,8 @@ you the same function:
 
 Depend on one of those directly if it is all you need; depend on this package
 for the full set of guards, validators, and helpers.
+
+## Documentation
+
+The API reference for `@openinf/util` and the other OpenINF packages is on the
+[OpenINF portal](https://open.inf.is/docs/sdk/), one version per release.

packages/util/package.json

@@ -34,6 +34,7 @@
     "test:coverage": "node --experimental-test-module-mocks --experimental-test-coverage --test-coverage-include='test-dist/src/**' --test 'test-dist/test/**/*.js'",
     "prepublishOnly": "npm run clean && npm run build"
   },
+  "homepage": "https://open.inf.is/docs/sdk/",
   "repository": {
     "type": "git",
     "url": "https://github.com/OpenINF/sdk.git",

tools/sync-package-metadata.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-// Normalizes the package-invariant metadata (repository, bugs, files,
+// Normalizes the package-invariant metadata (homepage, repository, bugs, files,
 // engines, author, license, types, exports) that every publishable
 // workspace package under packages/* should share, rewriting each
 // package.json from a single canonical definition instead of by
@@ -16,6 +16,7 @@ const path = require('path');
 const PACKAGES_DIR = path.join(__dirname, '..', 'packages');
 const REPO_URL = 'https://github.com/OpenINF/sdk.git';
 const ISSUES_URL = 'https://github.com/OpenINF/sdk/issues';
+const DOCS_URL = 'https://open.inf.is/docs/sdk/';
 const AUTHOR = 'The OpenINF Authors';
 const LICENSE = 'MIT';
 // The oldest Node.js release line still inside an LTS window. OpenINF supports
@@ -40,6 +41,7 @@ const FIELD_ORDER = [
   'exports',
   'sideEffects',
   'scripts',
+  'homepage',
   'repository',
   'bugs',
   'keywords',
@@ -101,6 +103,10 @@ function syncOne(dirName) {
   // here instead of letting this flatten it to false.
   pkg.sideEffects = false;
 
+  // npm shows the homepage as the package page's first link, which is where a
+  // reader looks for documentation, and the README is already on the page
+  // itself. Without one, npm falls back to the repository root.
+  pkg.homepage = DOCS_URL;
   pkg.repository = {
     type: 'git',
     url: REPO_URL,