@biffo/cli 0.274.0 → 0.275.1

package/_skeletons/plugin-template/web-admin/src/lib/api-core.test.ts

@@ -0,0 +1,125 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { ApiError, createRequest } from './api-core'
+
+/**
+ * Guards for the distributed admin-API request core (biffo-template#1492),
+ * and in particular for the `onError` mapper added so the marketing plugin
+ * could adopt it without losing its endpoint-specific messages.
+ */
+
+function jsonResponse(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'Content-Type': 'application/json' },
+  })
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
+function stubFetch(res: Response) {
+  const fetchMock = vi.fn().mockResolvedValue(res)
+  vi.stubGlobal('fetch', fetchMock)
+  return fetchMock
+}
+
+describe('createRequest without a mapper (the default path)', () => {
+  it('throws ApiError carrying the status and the response body', async () => {
+    stubFetch(new Response('you may not do that', { status: 403 }))
+    const request = createRequest(() => 'tok', '/base')
+
+    await expect(request('GET', '/thing')).rejects.toBeInstanceOf(ApiError)
+  })
+
+  it('falls back to statusText when the body is empty', async () => {
+    stubFetch(new Response('', { status: 500, statusText: 'Internal Server Error' }))
+    const request = createRequest(() => 'tok', '/base')
+
+    await expect(request('GET', '/thing')).rejects.toThrow('Internal Server Error')
+  })
+})
+
+describe('createRequest with an onError mapper', () => {
+  /**
+   * THE POINT OF THE HOOK. The mapper must be able to read the JSON body,
+   * which means `request()` must not have consumed the stream before calling
+   * it. A mapper handed an already-read Response sees an empty body and falls
+   * back to a generic message — the silent degradation this exists to stop.
+   */
+  it('hands the mapper a response whose body is still readable', async () => {
+    stubFetch(jsonResponse(403, { detail: 'you are not an admin of this brand' }))
+    const request = createRequest(
+      () => 'tok',
+      '/base',
+      async (res, context) => {
+        const body = (await res.json()) as { detail?: string }
+        throw new Error(`${body.detail} (${res.status}) while trying to ${context}`)
+      },
+    )
+
+    await expect(request('POST', '/links', {}, '/base', 'mint links')).rejects.toThrow(
+      'you are not an admin of this brand (403) while trying to mint links',
+    )
+  })
+
+  it('passes the per-call context through, and undefined when omitted', async () => {
+    const seen: (string | undefined)[] = []
+    stubFetch(jsonResponse(500, {}))
+    const request = createRequest(
+      () => 'tok',
+      '/base',
+      (_res, context) => {
+        seen.push(context)
+        throw new Error('mapped')
+      },
+    )
+
+    await expect(request('GET', '/a', undefined, '/base', 'load campaigns')).rejects.toThrow(
+      'mapped',
+    )
+    stubFetch(jsonResponse(500, {}))
+    await expect(request('GET', '/b')).rejects.toThrow('mapped')
+
+    expect(seen).toEqual(['load campaigns', undefined])
+  })
+
+  it('never reaches the default ApiError once the mapper has thrown', async () => {
+    stubFetch(jsonResponse(403, { detail: 'nope' }))
+    const request = createRequest(
+      () => 'tok',
+      '/base',
+      () => {
+        throw new Error('mapped')
+      },
+    )
+
+    // If the default path still ran, this would be an ApiError instead.
+    await expect(request('GET', '/thing')).rejects.not.toBeInstanceOf(ApiError)
+  })
+
+  /**
+   * A mapper is typed `=> never`, but types are not enforcement at runtime and
+   * this is the dangerous failure: a mapper that returns normally would let
+   * `request()` fall through to the default throw. That is recoverable. What
+   * must never happen is a failed request RESOLVING — so this pins that even a
+   * misbehaving mapper cannot turn a 403 into a successful call.
+   */
+  it('still throws if a mapper wrongly returns instead of throwing', async () => {
+    stubFetch(jsonResponse(403, { detail: 'nope' }))
+    const request = createRequest(() => 'tok', '/base', (() => undefined) as never)
+
+    await expect(request('GET', '/thing')).rejects.toBeInstanceOf(ApiError)
+  })
+
+  it('does not run the mapper on a successful response', async () => {
+    stubFetch(jsonResponse(200, { ok: true }))
+    const onError = vi.fn(() => {
+      throw new Error('should not run')
+    })
+    const request = createRequest(() => 'tok', '/base', onError as never)
+
+    await expect(request('GET', '/thing')).resolves.toEqual({ ok: true })
+    expect(onError).not.toHaveBeenCalled()
+  })
+})

package/_skeletons/plugin-template/web-admin/src/lib/api-core.ts

@@ -26,18 +26,48 @@ export class ApiError extends Error {
 
 export type GetIdToken = () => string | null | Promise<string | null>
 
+/**
+ * Maps a failed response into the error a plugin wants to surface, INSTEAD of
+ * the default `ApiError(status, body)`.
+ *
+ * It receives the `Response` with its body **unread**, so it can `.json()` the
+ * payload — Core returns `{"detail": "..."}` for a permission failure, and a
+ * plugin usually wants that sentence rather than a status code. It also
+ * receives the per-call `context` string, because the useful wording is
+ * endpoint-specific: "you need the admin role to **mint links**" is actionable
+ * where "403" is not.
+ *
+ * Added for biffo-template#1492. The marketing plugin could not adopt this core
+ * without it: `createRequest` read the body into a string and threw immediately,
+ * leaving no seam to inspect it first, so migrating would have collapsed a dozen
+ * hand-written, endpoint-specific messages into one generic status string. That
+ * is a behaviour regression, and the plugin correctly refused rather than
+ * dropping them — the gap was in this module, not in the plugin.
+ *
+ * MUST NOT RETURN NORMALLY: it either throws, or returns a rejected promise.
+ * The `never` return type says so; a mapper that falls through would make
+ * `request()` resolve `undefined` for a failed call, which is the silent-success
+ * shape this estate spends most of its time eliminating. `assertThrew` in
+ * `api-core.test.ts` holds that line.
+ */
+export type ErrorMapper = (
+  response: Response,
+  context: string | undefined,
+) => Promise<never> | never
+
 /**
  * Build a `request<T>(method, path, body?, base?)` function bound to a token
  * source and a default base. A plugin's own api.ts calls this once per
  * `createApi()` and defines its endpoints on top of the result — see the
  * starter `api.ts` in this same directory for the worked shape.
  */
-export function createRequest(getIdToken: GetIdToken, defaultBase: string) {
+export function createRequest(getIdToken: GetIdToken, defaultBase: string, onError?: ErrorMapper) {
   return async function request<T>(
     method: string,
     path: string,
     body?: unknown,
     base: string = defaultBase,
+    context?: string,
   ): Promise<T> {
     const token = await getIdToken()
     const res = await fetch(`${base}${path}`, {
@@ -49,6 +79,12 @@ export function createRequest(getIdToken: GetIdToken, defaultBase: string) {
       ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
     })
     if (!res.ok) {
+      // The mapper runs FIRST, and gets the response with its body still
+      // unread. Order is load-bearing: `res.text()` below consumes the stream,
+      // and a mapper handed an already-consumed Response cannot call `.json()`
+      // — it would silently see an empty body and fall back to a generic
+      // message, which is the exact failure this hook exists to prevent.
+      if (onError) await onError(res, context)
       // Read the body for the reason: Core returns a JSON detail for a
       // permission failure, and "403" alone tells an admin nothing about
       // which rule bit.

package/_skeletons/sibling-template/AGENTS.md

@@ -117,6 +117,42 @@ it deliberately and say so in a comment; never steal a fresh one.
 - **Squash-merge, delete the branch, remove the worktree:**
   `gh pr merge <N> --squash --delete-branch`.
 
+### If you were dispatched by another agent, you do NOT wait and you do NOT merge
+
+Everything above assumes the session doing the work is also the session that
+will merge it. **A delegated subagent is not that session.** If an orchestrator
+spawned you to do one unit of work, your finished state is:
+
+> branch pushed → PR opened → **report back immediately**, with the PR number
+> and what you changed.
+
+Do **not** run `wait-for-checks`. Do **not** merge. The orchestrator watches CI
+and merges, and sends you back if CI fails on your change.
+
+**Why this is a rule and not a preference.** A subagent has no way to sleep. Told
+to wait for CI, it stops, wakes, re-reads the same pending status, and stops
+again — and every wake is a full context reload that reports nothing new. Measured
+on 2026-08-11: one dispatch tranche produced **25+ wake-ups** returning only
+"still waiting"; a single agent burned ~145k tokens re-reading a queued deploy
+before it was killed. The orchestrator does the same wait for nothing extra: it
+is already awake, and one loop covers every PR in the tranche at once instead of
+N agents each paying a context reload for the same minutes.
+
+**The instruction is the cause, so the fix lives here.** Both of those incidents
+happened in sessions whose dispatch briefs ended "get CI green, then squash-merge"
+— written by an orchestrator that _had already recorded the lesson_ and then
+followed §5 above, which says exactly that. §5 is right for the session that owns
+the work and wrong for a delegate, and until now nothing said so.
+
+**Keep a delegate alive only when it still has a DECISION to make** — a real test
+failure to diagnose, a design question to answer. "Wait, then merge" is not a
+decision.
+
+Orchestrators: end every dispatch brief with the finished state above, and reach
+for `gh pr merge --auto` when the merge needs no judgement — then still verify,
+because `--auto` waits for ever on a check that cannot re-evaluate itself (a
+`Release Guards` closing-keyword failure needs a re-run, not a wait).
+
 ## 6. Push honestly, and verify the remote has your commit
 
 - **Push with the exit status visible:** `git push origin HEAD; echo $?`. A pipe

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@biffo/cli",
-  "version": "0.274.0",
+  "version": "0.275.1",
   "description": "Biffo project scaffolding CLI",
   "license": "MIT",
   "type": "module",