@duyquangnvx/create-agent-cli 0.30.1 → 0.31.0

package/CHANGELOG.md

@@ -4,6 +4,35 @@ What changed in each release of `@duyquangnvx/agent-cli` (the Runtime) and `@duy
 
 ## Unreleased
 
+## v0.31.0 (2026-11-10)
+
+### Added
+
+- `ctx.latestRelease(version)` passes on a release the CLI's own server named. On a Global install, a version higher than the running release and than any a server named before starts the Release check at once instead of on its daily turn; a later run's Release notice names what the Install registry returned, never the server's version. It does nothing on a Dependency install, or with `<NAME>_NO_RELEASE_CHECK` or `CI` set.
+- `ctx.userFile(name, schema)` gives `read`, `write` and `remove` for a JSON User file at `$XDG_STATE_HOME/<cli>/<name>.json` (`~/.local/state` when unset or empty), for state the CLI writes such as a stored login: its folder is 0700 and the file 0600, `write` replaces it atomically, and `read` gives `undefined` for a file that is missing, not JSON, or rejected by the schema. `UserFile` and `UserFileOf` are exported.
+- `runtimeCodes.RELEASE_TOO_OLD`, a Runtime code of class caller (exit 1) that any Command may throw without declaring it when its server refuses this release as too old. The Runtime puts the Install's update line first among its Next steps: `<name> update` on a Global install, the package manager's line, such as `pnpm up --latest <package>`, on a Dependency install. Release checks being off does not hide it.
+- `ctx.fetch(url, init)` sends one request with `fetch`'s own arguments plus `timeoutMs`, and never resends it. It sends `User-Agent: <cli>/<version>` unless the Command sets one, and bounds the request, body included, by `ctx.deadline(timeoutMs)`, 30 s by default. A server it cannot reach fails the run with the new Runtime code `UNREACHABLE`, and a 5xx, 408 or 429 answer with `UNAVAILABLE`, both exit 75 with the rerun as Next step, `retryAt` from `Retry-After` (seconds or an HTTP date) and `origin` and `status` in `details`; every other answer returns to the Command. `runCli` takes a `fetch` option that `ctx.fetch` sends through in a test. `ContextFetch` and `FetchInit` are exported.
+- A Login: `defineCli({ logins })` names OAuth servers that grant a token through the device flow (RFC 8628), each by its `deviceEndpoint`, `tokenEndpoint`, optional `revokeEndpoint`, `clientId`, optional `scope` and optional `secret`, whose value wins over the stored Login. A Command lists the Logins it needs in `logins`, and `ctx.login(name)`, typed to those names, gives the token: the Secret's value, else the stored Login, kept as a User file per token endpoint and client id. A Command whose Login is found neither way starts an Approval before it runs, or takes up the pending one, and fails with the new Runtime code `APPROVAL_PENDING` (exit 75): the link and code in `details`, a hint to write them in the reply, and the rerun with `--wait 100` as the Next step. `--wait <seconds>` is a Standard flag of every Command that declares a Login: the rerun polls the same Approval that long and runs the Command once approved. A rerun without `--wait` still polls a pending Approval once, so one approved meanwhile runs the Command. A dry run never refreshes a stored Login, counting one whose access token expired as missing, and starts no Approval: it fails with the new Runtime code `LOGIN_REQUIRED` (exit 2), with `login <name>` and the rerun as Next steps, as it does when its plan throws `LOGIN_REJECTED` for a stored Login. `defineCli` throws on a Login a Command lists that the CLI does not declare, and a CLI with one Command takes no `logins`. `LoginDeclaration` is exported.
+- The Built-in `login [name]`, for a CLI that declares a Login, which a Coding agent may run: it asks for an Approval, prints the link and code on stderr, polls at the server's interval plus 5 s per `slow_down`, and stores the Login once the person approves; the name may be left out when there is one Login. The pending Approval is kept as a User file, so a rerun takes up the same code. It waits `--wait N` seconds, 100 when absent, then fails with the new Runtime code `APPROVAL_PENDING` (exit 75), the link and code in `details` and `login <name> --wait 100` as the Next step. A refused code fails with `APPROVAL_DENIED` and an expired one with `APPROVAL_EXPIRED`, both exit 2 with `login <name>` as the Next step. With the Secret set, or a stored Login whose access token has not expired, it does nothing; one whose access token expired it refreshes, asking for an Approval only when the server refuses the refresh.
+- The Built-in `logout [name]`, for a CLI that declares a Login: it revokes the stored Login at the Login's `revokeEndpoint` per RFC 7009, sending its refresh token or else its access token, then removes it; without a `revokeEndpoint` it only removes it, and without a stored Login it does nothing. A revocation the server could not answer fails as `ctx.fetch` does and keeps the Login for the rerun. It never touches the Login's Secret, and names it when it is still set.
+- `doctor` reports a `login <name>` row per Login: the Secret it reads its token from, a stored Login, or, when there is neither, an advisory problem with `login <name>` as its fix, which does not fail `doctor`.
+- `ctx.fetch` never lets a write be applied twice: a POST or PATCH, or a request marked `once: { check? }`, that may have arrived but got no answer (a dropped connection, `timeoutMs`, Ctrl-C or the run deadline), or got a 408 or a 5xx other than 503, fails the run with the new Runtime code `UNANSWERED`, exit 3, never the rerun. Its Next step is `check` when given; without one, its hint says to ask whoever runs the server. A connection refused before sending stays `UNREACHABLE`, and a 503 or 429 stays `UNAVAILABLE`. `once: false` declares a POST or PATCH safe to send again, such as an OAuth device-flow token poll.
+- A stored Login with a refresh token is refreshed (RFC 6749 §6) before a Command that needs it runs, once its access token expires within 5 minutes, and `ctx.login` gives the new token. The refresh runs under `ctx.runToEnd` and stores the new pair in one atomic write, so Ctrl-C never spends a single-use refresh token without keeping its successor. A refresh refused with `invalid_grant` drops the Login and starts an Approval, failing with `APPROVAL_PENDING` as a missing Login does.
+- `runtimeCodes.LOGIN_REJECTED`, which a Command that declares a Login throws without declaring it when its server refuses the token, naming the Login in `details.login` when it has several. A stored Login is dropped and the run starts an Approval and fails with `APPROVAL_PENDING` (exit 75); a token from the Login's Secret fails with `LOGIN_REJECTED` (exit 2), its hint naming the Secret, and touches no file.
+- `ctx.fetch` takes `ignoreStop: true`, bounding the request as `ctx.deadline(timeoutMs, { ignoreStop: true })` does, so neither Ctrl-C nor the run deadline cuts short a request inside `ctx.runToEnd`.
+
+### Changed
+
+- A Notice reaches the caller at most once per run: `ctx.notice` with a text it already gave in this run writes nothing, so a Command that calls it once per server call need not count calls itself. Progress lines are still all written.
+- **Breaking:** `UNREACHABLE`, `UNAVAILABLE` and `UNANSWERED` are Runtime codes, so a CLI whose Error table declares any of them throws at `agentCli`: rename the code, or send the request through `ctx.fetch` and drop it.
+- `--help` always lists exit 3, since any Command's `ctx.fetch` can end in `UNANSWERED`.
+- **Breaking:** `LOGIN_REQUIRED`, `LOGIN_REJECTED`, `APPROVAL_PENDING`, `APPROVAL_DENIED` and `APPROVAL_EXPIRED` are Runtime codes, so a CLI whose Error table declares any of them throws at `agentCli`, and a CLI that declares a Login cannot define its own `login` or `logout` Command. A Command that declares a Login cannot declare a `wait` option.
+- The scaffolded template pins `@duyquangnvx/release` 0.11.0, whose Device Approval for an API Skill Hub speaks OAuth's device flow (RFC 8628).
+
+### Fixed
+
+- On Windows, the Release check runs an npm found on `PATH` unquoted, so `cmd.exe` finds `npm.cmd`'s own folder: before, the check failed whenever no npm sat beside Node, and a newer release was never told.
+
 ## v0.30.1 (2026-11-09)
 
 ### Fixed