@arbol-ai/cli 1.20261018.213455 → 2.1.0

package/README.md

@@ -3,25 +3,18 @@
 `arbol`, the Arbol API from your terminal. Its commands are generated by
 [Cloudflare Forge](https://github.com/cloudflare/forge) from the platform's public OpenAPI,
 [`https://api.getarbol.com/openapi.json`](https://api.getarbol.com/openapi.json), and every request
-goes through [`@arbol-ai/sdk`](https://www.npmjs.com/package/@arbol-ai/sdk). A release's version is
-the date and time it was built (`1.YYYYMMDD.HHMMSS`, UTC); `arbol --version` also names the API release
-its commands were generated from.
+goes through [`@arbol-ai/sdk`](https://www.npmjs.com/package/@arbol-ai/sdk). Its versions are semver,
+from 2.1.0 on (see [Releases](#releases)); `arbol --version` also names the API release its commands
+were generated from, as in `arbol 2.1.0 (Arbol API 1.20261019.4056)`.
 
 ```sh
 npm install --global @arbol-ai/cli
 arbol --version
 ```
 
-It needs Node.js 26 or newer, whose `fetch` and `Temporal` the SDK uses. On macOS and Linux,
-[cli.getarbol.com](https://cli.getarbol.com) does the same in one line:
-
-```sh
-curl -fsSL https://cli.getarbol.com/install.sh | sh
-```
-
-[`install.sh`](site/public/install.sh) checks for Node.js 26 and runs
-`npm install --global @arbol-ai/cli`, or prints that command when npm is missing. Run it again to
-update; `ARBOL_VERSION=<version>` installs a given release.
+It needs Node.js 26 or newer, whose `fetch` and `Temporal` the SDK uses. The same command updates it.
+An `arbol` installed before the CLI was on npm comes first or blocks the install: remove it with
+`npm uninstall --global @getarbol/cli`, or delete `~/.local/bin/arbol` and `~/.local/share/arbol`.
 
 ## Profiles
 
@@ -161,20 +154,34 @@ A release of the API flows through three repositories, each started by the one b
 1. **project-arbol-gateway** publishes the OpenAPI at `https://api.getarbol.com/openapi.json` and sends
    `openapi-release` to project-arbol-sdk-js.
 2. **project-arbol-sdk-js** regenerates `@arbol-ai/sdk` from it, publishes it to npm and sends
-   `sdk-release` (`{ "version": "<release>" }`) here.
-3. **Here**, [Generate](.github/workflows/generate.yml) pins `@arbol-ai/sdk` to exactly that release,
-   regenerates `src/generated/` from the live OpenAPI and, when anything changed and `bun run verify`
-   passes, commits `Release <release>` to main and runs [Publish](.github/workflows/publish.yml) on that
-   commit. When nothing changed, nothing is committed or published.
-
-Generate also runs every 6 hours and by hand, pinning the SDK release the OpenAPI names once it is on
-npm. Its push uses an installation token of the organization's GitHub App (Arbol Bot: the variable
-`ARBOL_BOT_APP_ID` and the secret `ARBOL_BOT_PRIVATE_KEY`), so the commit runs Verify like any other.
-Publish can also run by hand, for a change to the CLI alone; npm receives the package with the
-organization's `NPM_TOKEN` and a provenance statement.
-
-[cli.getarbol.com](https://cli.getarbol.com) is the Worker in [`site/`](site/wrangler.jsonc): static
-files and no code. Cloudflare Workers Builds deploys it on every push to main that changes `site/`.
+   `sdk-release` here: `{ "version": "<SDK version>", "openapi": { "release": "...", "sha256": "..." } }`.
+3. **Here**, [Generate](.github/workflows/generate.yml) releases when the OpenAPI's content changed:
+   the SHA-256 of its canonical JSON without `info.version` (keys sorted, no whitespace; see
+   [`generation/openapi-hash.ts`](generation/openapi-hash.ts), the same hash sdk-js computes), compared
+   with `openapiContentSha256` in main's `src/generated/generation.json`. It also releases when the
+   `@arbol-ai/sdk` to pin is not the one main pins. Otherwise the run stops and nothing is committed or
+   published. A release pins `@arbol-ai/sdk` exactly, regenerates `src/generated/`, and when
+   `bun run verify` passes commits `Release Arbol API <release> with @arbol-ai/sdk <version>` to main and
+   runs [Publish](.github/workflows/publish.yml) on that commit with `bump: minor`.
+
+The SDK Generate pins is the version `sdk-release` names. Every 6 hours and by hand, Generate runs the
+same check and pins the highest `@arbol-ai/sdk` whose published `package.json` says it was generated
+from the same OpenAPI content (`arbol.openapi.sha256`); while there is none, it stops with a notice,
+since the SDK is released first. Its push uses an installation token of the organization's GitHub App
+(Arbol Bot: the variable `ARBOL_BOT_APP_ID` and the secret `ARBOL_BOT_PRIVATE_KEY`), so the commit runs
+Verify like any other.
+
+Versions are semver, computed by Publish from the highest version on npm
+([`generation/release.ts`](generation/release.ts)):
+
+- A release from Generate raises the minor: 2.1.0, then 2.2.0. The first 2.x release is 2.1.0; before it
+  versions were the build's date and time (`1.YYYYMMDD.HHMMSS`).
+- A change to the CLI's own code, which the OpenAPI does not carry, is released by running Publish by
+  hand on main. Its `bump` input raises the `patch` (the default), `minor` or `major`.
+
+The published `package.json` records the OpenAPI the commands were generated from:
+`"arbol": { "openapi": { "release": "<info.version>", "sha256": "<content hash>" } }`. npm receives the
+package with the organization's `NPM_TOKEN` and a provenance statement.
 
 ## License