Skip to main content
Date: 2026-10-10

​
Status

Accepted

​
Context

The docs list every built-in adapter (with the variable that holds its credential and the one that overrides its API base URL) and every secret scheme (with the reference form and how it is resolved). Those lists are generated by pnpm docs:gen, but the facts they show were kept in two hand-written maps in scripts/gen-docs.ts, while the same variable names were written again, as string literals, in each adapter’s code. A first-contributor walkthrough showed the cost: a new adapter meant editing the generator script (the adapter scaffold had to patch it by regular expression), and nothing tied the documented variable name to the one the code actually read. The two could disagree silently.

​
Decision

  • ResourceAdapter has an optional about: { credentialEnv, baseUrlEnv? }. Each adapter declares it once, as a constant its own code uses (requireEnv(actx.env, ABOUT.credentialEnv, …)), and the generated docs read it from the registry.
  • SecretSource has optional form and resolvedBy, written next to the source’s resolve.
  • Both are optional in the type so third-party plugins keep compiling; pnpm docs:gen fails for a built-in adapter or source that leaves them out.
  • A source’s resolve throws a reason only; the engine prefixes the reference once. The message never contains the value.

​
Consequences

  • Adding an adapter or a secret source touches only its own file, its registration, its tests and its docs section; scripts/gen-docs.ts no longer changes, and the scaffold no longer edits it.
  • The documented variable name is the one the code reads, by construction.
  • The public adapter contract grew by one optional field and one type (AdapterAbout). Plugins may adopt it to be listed by future tooling; nothing requires it of them.