feat(auth): refresh an expiring OAuth token before token view / status

[scottlovegrove]

Problem

tdc auth token view read the access token straight from the store and never triggered a refresh. Once an OAuth access token expired it kept printing the same dead token until some other API command happened to rotate it, which defeats the point of export COMMS_API_TOKEN="$(tdc auth token view)" for scripts and MCP servers. tdc auth status worked around the same gap by re-reading the store through getApiTokenSnapshot inside fetchLive.

Change

Bumps @doist/cli-core to 1.6.0 (Doist/cli-core#135) and wires its new refresh option on both attachers via a shared getTokenRefreshOptions() in src/lib/auth.ts. The DCR handshake is resolved per account through the function form, since cli-core doesn't persist the client metadata the refresh grant needs; getCommsOAuthRefreshHandshake still raises NO_TOKEN for partial metadata, so a stored OAuth token without a client id fails the same way it does on the API path rather than letting cli-core POST a grant with no client id.

• token view: rotates an expiring OAuth token before printing. Manual-token accounts and COMMS_API_TOKEN have no refresh token and are served from the single bundle read, so their behaviour is unchanged. The env-var guard still runs before any refresh.
• status: fetchLive now takes the token cli-core hands it instead of re-reading through getApiTokenSnapshot. One fewer store read, and the same fallback rules as token view.
• getActiveSnapshot (the API path) now threads ref into refreshAccessToken, so tdc --user <ref> … rotates the selected account rather than the default one.

Tests

• auth.test.ts: the global --user status test now drives cli-core's real refresh with a fake provider and asserts the ref reaches every bundle read, the rotated bundle is persisted, and fetchLive probes with the new token.
• lib/auth.test.ts: getTokenRefreshOptions returns the expected lock path / skew and its handshake resolver delegates to getCommsOAuthRefreshHandshake, including the NO_TOKEN rejection for partial metadata.

Skill content and README updated for the token view behaviour; SKILL.md regenerated.

[doistbot]

This PR wires cli-core 1.6.0's new refresh option into token view and status via a shared getTokenRefreshOptions() helper, so expiring OAuth tokens get rotated before being printed or probed, and threads the global --user ref through the API-path refresh. The env-var guard, handshake reuse, and lock-path/skew constants all line up with the existing auth flow, and no security or reuse issues surfaced.

Few things worth tightening:

• Preserve the legacy-token fallback: cli-core now resolves the handshake as soon as a bundle enters the 60-second refresh skew, so an OAuth record without oauthClientId throws even while its access token is still valid — auth status and auth token view can fail up to a minute earlier than API commands, which deliberately serve that token until it's actually expired. Defer the missing-metadata failure until refresh is truly needed, or have these attachers retain the valid token.
• The headline token view refresh path is untested: every token view test runs with getTokenRefreshOptions mocked to return undefined, so the refresh option on attachTokenViewCommand is never exercised — removing it (or a cli-core regression) would keep the suite green while a dead token prints again. Add a test mirroring the new status test: expiring OAuth bundle + fake provider, assert stdout prints the rotated token.

I also included a few optional follow-up notes in the details below.

Optional follow-up notes (3)

• src/lib/auth.ts:74: getTokenRefreshOptions() now owns the refresh wiring, but getActiveSnapshot still builds the same provider / skewMs / lockPath / handshake values inline when it calls refreshAccessToken (lines 145-148). Reuse the builder there — e.g. refreshAccessToken({ store, ref, ...getTokenRefreshOptions() }) — so the API path and the two attachers can't drift.
• src/commands/auth/auth.test.ts:626: not.toHaveBeenCalledWith(undefined) is vacuous here. withUserRefAware.activeBundle substitutes the global ref (ref ?? requestedRef) before the underlying storeMocks.activeBundle is reached, so with --user 1 the mock only ever sees '1'. This assertion cannot detect a missing ref on cli-core's under-lock re-read despite the comment above it. Drop it, or assert call count/arguments at the wrapper level.
• src/commands/auth/auth.test.ts:633: The comment says the rotated bundle is persisted, but the assertion only checks the new access token. The fake provider also returns rt_refreshed_1234567890; if cli-core persisted the access token while dropping the rotated refresh token, this test would still pass and later refreshes would reuse the stale token. Assert the new refresh token (and expiry) as well, or narrow the comment.

_{Share Feedback • Review Logs}

[doist-release-bot]

🎉 This PR is included in version 3.3.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀