happyskills 1.13.0 → 1.13.1

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.13.1] - 2026-06-29
+
+### Fixed
+
+- Stop a transient session-refresh hiccup from becoming a terminal "session expired" auth failure on a **write** (`publish`/`release` and other authenticated writes). When your `id_token` had expired and the automatic refresh blipped (a network/cold-start failure on the refresh call), the CLI would fire the write with no token, the API would answer `401`, and that was rendered as `AUTH_REQUIRED` ("your session has expired … run `happyskills login`") — aborting the command even though an immediate retry succeeds. Now, when valid credentials exist on disk but the token simply couldn't be refreshed at that moment, a write surfaces a **retryable** `NETWORK_ERROR` (a `retry` `next_step`) instead of sending a tokenless request. The guard is deliberately narrow: **reads are unchanged** (a `GET` still degrades to anonymous/public results), a **corrupt/unreadable credentials file** still falls through to re-login (it is not turned into an infinite "please retry" loop), and the genuinely-not-signed-in case (no credentials) is unchanged. (Spec 260629-02.)
+
 ## [1.13.0] - 2026-06-29
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "1.13.0",
+	"version": "1.13.1",
 	"description": "Package manager for AI agent skills",
 	"license": "SEE LICENSE IN LICENSE",
 	"author": "Nicolas Dao <nic@cloudlesslabs.com> (https://cloudlesslabs.com)",

package/src/api/client.js

@@ -2,7 +2,7 @@ const { createHash } = require('crypto')
 const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
 const { API_URL, CLI_VERSION } = require('../constants')
 const { ApiError, NetworkError, AuthError } = require('../utils/errors')
-const { load_token } = require('../auth/token_store')
+const { load_token, credentials_present } = require('../auth/token_store')
 const { get_envelope, set_envelope } = require('../utils/intent')
 
 const get_base_url = () => process.env.HAPPYSKILLS_API_URL || API_URL
@@ -29,10 +29,28 @@ const request = (method, path, options = {}) => catch_errors(`API ${method} ${pa
 
 	let token_attached = false
 	if (auth) {
-		const [, token_data] = await load_token()
+		const [token_err, token_data] = await load_token()
 		if (token_data) {
 			headers['Authorization'] = `Bearer ${token_data.id_token}`
 			token_attached = true
+		} else if (!token_err && credentials_present() && method !== 'GET' && method !== 'HEAD') {
+			// A WRITE (non-GET/HEAD) where load_token returned CLEANLY (no error) with no
+			// token, yet the credentials file still exists. That is uniquely the
+			// TRANSIENT-refresh-failure branch: a real session whose id_token expired and
+			// whose proactive refresh blipped (network / cold start) — load_token preserves
+			// the still-valid file and returns [null, null]. Permanent failures (Cognito
+			// rejected the token) and the no-refresh-token case both DELETE the file, and a
+			// corrupt/unreadable file returns [errors, undefined] (token_err set) — so
+			// guarding on `!token_err && file-present` isolates the genuinely-retryable case
+			// and lets a corrupt file fall through to a tokenless request (→ server 401 →
+			// re-login, which overwrites the bad file) rather than a dead retry loop.
+			// Firing a tokenless WRITE in the transient case makes the API answer 401 and
+			// the CLI render it as a terminal AUTH_REQUIRED "your session has expired" — the
+			// spurious-AUTH_REQUIRED bug (spec 260629-02). Surface a retryable error instead.
+			// Scoped to writes ONLY: a read (GET/HEAD) keeps its pre-existing behavior —
+			// proceed tokenless and degrade to anonymous/public results (spec §6.3: "keep
+			// the read-path behavior unchanged"); a write must not silently lose authorship.
+			throw new NetworkError('Your session could not be refreshed right now (a temporary issue). Please retry.')
 		}
 	}
 

package/src/api/client.test.js

@@ -122,3 +122,156 @@ describe('api client — 401 message never tells a signed-in user to log in', ()
 		})
 	})
 })
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Transient backend failure on a write/publish path (spec 260629-02). The API no
+// longer maps a transient verify/lookup hiccup to a 401 "session expired" — it
+// returns a retryable 503 DB_UNAVAILABLE. The CLI must surface that as a RETRY
+// affordance, NOT collapse it into an AUTH_REQUIRED / "run login" dead-end. This
+// is the operator-facing half of the fix: an authenticated, authorized operator
+// whose publish hit a blip is told to retry (and an immediate retry succeeds),
+// instead of being sent down a pointless re-login path.
+// ─────────────────────────────────────────────────────────────────────────────
+
+const with_503 = async (code, fn) => {
+	const orig = global.fetch
+	global.fetch = async () => ({
+		ok: false,
+		status: 503,
+		headers: { get: () => null },
+		json: async () => ({ error: { code, message: 'Authentication is temporarily unavailable. Please retry.' } }),
+	})
+	try { return await fn() } finally { global.fetch = orig }
+}
+
+describe('api client — transient 503 on publish surfaces retry, not a login dead-end (spec 260629-02)', () => {
+	const { next_step_for_error } = require('../constants/next_step_by_error_code')
+
+	it('a 503 DB_UNAVAILABLE on push preserves the retryable code (NOT AUTH_REQUIRED)', async () => {
+		await with_503('DB_UNAVAILABLE', async () => {
+			const [errors] = await client.post('/repos/acme/deploy/push', { commit: 'x' }, { auth: false })
+			assert.ok(errors, 'expected an error tuple')
+			const err = errors.find(e => e && e.name === 'ApiError')
+			assert.ok(err, 'a 503 must surface as an ApiError, not an AuthError')
+			assert.equal(err.code, 'DB_UNAVAILABLE')
+			assert.notEqual(err.code, 'AUTH_REQUIRED')
+			assert.equal(err.status_code, 503)
+		})
+	})
+
+	it('the operator-facing next_step for that code is RETRY, not login', () => {
+		const next_step = next_step_for_error('DB_UNAVAILABLE', 'whatever', {})
+		assert.equal(next_step.action, 'retry')
+		assert.notEqual(next_step.action, 'login')
+	})
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// The ACTUAL 2026-06-29 incident (spec 260629-02 Findings): the operator's session
+// had expired and the CLI's proactive token refresh hit a TRANSIENT failure. On a
+// transient refresh failure, load_token preserves the (still-valid) refresh_token
+// on disk but returns null — so the client fired an authed request WITHOUT a token,
+// the API answered 401 (no-token branch), and the CLI rendered it as AUTH_REQUIRED
+// "session expired". An immediate retry (after the refresh blip cleared) succeeded.
+//
+// The fix: a real session whose token can't be refreshed *right now* (file present
+// but load_token null) must surface a RETRYABLE error, never a tokenless request
+// that turns into a terminal "session expired".
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('api client — transient token-refresh failure → retry, never a tokenless 401 (spec 260629-02)', () => {
+	const auth_path = require.resolve('./auth')
+
+	const write_expired_token = (dir) => {
+		const token = {
+			id_token: 'expired-id-token',
+			access_token: 'expired-access-token',
+			refresh_token: 'still-valid-refresh-token',
+			expires_in: 1,
+			stored_at: new Date(Date.now() - 5000).toISOString(),
+		}
+		fs.mkdirSync(path.join(dir, 'happyskills'), { recursive: true })
+		fs.writeFileSync(path.join(dir, 'happyskills', 'credentials.json'), JSON.stringify(token), { mode: 0o600 })
+	}
+
+	// Make the refresh endpoint fail transiently (NetworkError) for both attempts.
+	const with_transient_refresh = async (fn) => {
+		const { NetworkError } = require('../utils/errors')
+		const orig = require.cache[auth_path]
+		require.cache[auth_path] = {
+			id: auth_path, filename: auth_path, loaded: true,
+			exports: { refresh: async () => [[new NetworkError('refresh endpoint unreachable')], null] },
+		}
+		try { return await fn() } finally {
+			if (orig) require.cache[auth_path] = orig; else delete require.cache[auth_path]
+		}
+	}
+
+	it('expired session + transient refresh blip on a push → retryable NetworkError, no tokenless request, NOT AUTH_REQUIRED', async () => {
+		await with_tmp_config(async (dir) => {
+			write_expired_token(dir)
+			await with_transient_refresh(async () => {
+				let fetched = false
+				const orig_fetch = global.fetch
+				global.fetch = async () => { fetched = true; return { ok: true, status: 200, headers: { get: () => null }, json: async () => ({ data: {} }) } }
+				try {
+					const [errors] = await client.post('/acme/deploy/push', { commit: 'z' })
+					assert.ok(errors, 'expected an error tuple')
+					assert.equal(fetched, false, 'must NOT fire a tokenless authed request when the session merely failed to refresh')
+					assert.ok(errors.find(e => e && e.name === 'NetworkError'), 'a transient refresh failure must surface as a retryable NetworkError')
+					assert.ok(!errors.find(e => e && e.name === 'AuthError'), 'must NOT surface AUTH_REQUIRED / "session expired" for a transient refresh blip')
+				} finally { global.fetch = orig_fetch }
+			})
+		})
+	})
+
+	it('NO credentials at all → proceeds tokenless (anonymous), unchanged', async () => {
+		await with_tmp_config(async () => {
+			// No creds file written → genuinely not signed in.
+			let fetched = false
+			const orig_fetch = global.fetch
+			global.fetch = async () => { fetched = true; return { ok: true, status: 200, headers: { get: () => null }, json: async () => ({ data: {} }) } }
+			try {
+				await client.get('/repos:search')
+				assert.equal(fetched, true, 'with no session, the request still goes out (server decides auth)')
+			} finally { global.fetch = orig_fetch }
+		})
+	})
+
+	it('transient refresh blip on a GET (read) → proceeds tokenless (anonymous), read-path unchanged (spec §6.3)', async () => {
+		await with_tmp_config(async (dir) => {
+			write_expired_token(dir)
+			await with_transient_refresh(async () => {
+				let fetched = false
+				const orig_fetch = global.fetch
+				global.fetch = async () => { fetched = true; return { ok: true, status: 200, headers: { get: () => null }, json: async () => ({ data: {} }) } }
+				try {
+					const [errors] = await client.get('/repos:search')
+					assert.equal(fetched, true, 'a read must still go out tokenless during a refresh blip (degrade to anonymous), not throw')
+					assert.ok(!errors || !errors.find(e => e && e.name === 'NetworkError'), 'reads keep their pre-existing anonymous-degrade behavior')
+				} finally { global.fetch = orig_fetch }
+			})
+		})
+	})
+
+	// A corrupt/unparseable credentials file ALSO leaves the file on disk while
+	// load_token yields no token — but it returns an ERROR (JSON.parse throws),
+	// NOT a clean null like the transient-refresh branch. It must NOT be treated as
+	// a retryable refresh blip (retrying never fixes a corrupt file → a dead loop).
+	// The actionable path is the pre-existing one: proceed tokenless so the server
+	// 401s and the user is steered to re-login (which overwrites the bad file).
+	it('corrupt credentials file → does NOT become a retry loop; proceeds tokenless so re-login is reachable', async () => {
+		await with_tmp_config(async (dir) => {
+			fs.mkdirSync(path.join(dir, 'happyskills'), { recursive: true })
+			fs.writeFileSync(path.join(dir, 'happyskills', 'credentials.json'), 'not-valid-json{{{', { mode: 0o600 })
+			let fetched = false
+			const orig_fetch = global.fetch
+			global.fetch = async () => { fetched = true; return { ok: true, status: 200, headers: { get: () => null }, json: async () => ({ data: {} }) } }
+			try {
+				const [errors] = await client.post('/acme/deploy/push', { commit: 'z' })
+				assert.equal(fetched, true, 'a corrupt creds file must proceed tokenless (server → 401 → login), not throw a retryable error')
+				assert.ok(!errors || !errors.find(e => e && e.name === 'NetworkError'), 'a corrupt creds file must NOT be reported as a transient/retryable refresh failure')
+			} finally { global.fetch = orig_fetch }
+		})
+	})
+})

package/src/auth/token_store.js

@@ -97,6 +97,15 @@ const load_token = () => catch_errors('Failed to load token', async () => {
 	return data
 })
 
+// Synchronous presence check for the credentials file. Used by the API client to
+// tell "no session at all" (file absent) apart from "a real session whose token
+// could not be refreshed right now" (file present but load_token returned null —
+// the transient-refresh-failure branch preserves the file, whereas permanent /
+// no-refresh-token failures delete it). See spec 260629-02.
+const credentials_present = () => {
+	try { return fs.existsSync(credentials_path()) } catch { return false }
+}
+
 const clear_token = () => catch_errors('Failed to clear token', async () => {
 	const creds_path = credentials_path()
 	try {
@@ -115,4 +124,4 @@ const require_token = async () => {
 	return data
 }
 
-module.exports = { save_token, load_token, clear_token, require_token }
+module.exports = { save_token, load_token, clear_token, require_token, credentials_present }