Skip to content

ADR 0036

github-actions[bot] edited this page Nov 22, 2026 · 2 revisions

Status: accepted · Built: planned · Date: 2026-11-19 · Supersedes: 0027, 0031 · Superseded by: 0051

Built: provisioning in the CLI package (spotcraft/provision), a schema per app in the apps database, legacy per-app databases kept; the agent no longer ships the kit, and a release no longer checks that the kit is published. The CLI is renamed @kodentuzo/spotcraft (export @kodentuzo/spotcraft/provision); its first publish and deprecating the old spotcraft package on npm are left to the release. Also built: spotkit 0.1 in kodentuzo/spotkit (user(request) from a JWT, a session cookie or a session token, clientAddress, health). Guests are made in the browser with Better Auth's client, not by spotkit: from the app's server, every new guest would come from the server's address and hit the per-address limit. To build in wave 1: publishing spotkit; @spotcraft/kit and the spotcraft npm package deprecated. Partly superseded by 0051: the kit is removed from this repository (it was kept, deprecated); deprecating @spotcraft/kit on npm is left to the owner.

The kit becomes spotkit, outside this repository

Context

@spotcraft/kit does two jobs. For the platform, it provisions app databases and their auth schema (used by the agent and the CLI). For apps, it does guest accounts, migrations, health, the client address, and has adapters for Nuxt and TanStack Start (ADR 0031). Because of the first job, it shares a release process with the platform (ADR 0027), and the platform and every app depend on the same package.

With a user pool per instance (ADR 0035), apps no longer need auth in their database, and the remaining app helpers have nothing to do with Spotcraft's internals.

Decision

  • Provisioning moves into the platform: provision and purge live in the CLI package, as its spotcraft/provision export, and the agent imports them from there. They can't be a private package, because the published CLI needs them. The export is for Spotcraft only, not for apps. They create an app's role and schema in the instance database (ADR 0034), nothing else.
  • App helpers become @kodentuzo/spotkit, in its own repository, kodentuzo/spotkit, with its own version. It uses Web Request, Response and Headers only, and has no framework adapters:
    • verifyUser(request) checks a bearer token or session JWT against AUTH_JWKS_URL;
    • guest(request) gets or creates the guest through AUTH_URL;
    • clientAddress(headers), health().
  • No migration runner. The server runs an app's migrations with the app's own tool, such as Drizzle's migrator (ADR 0034), so the kit's migrateApp (ADRs 0031 and 0032) isn't carried over.
  • spotkit is optional. Everything it does is in docs/contracts.md, so an app can do it by hand or in another language.
  • The CLI is published as @kodentuzo/spotcraft (the command stays spotcraft), with the project's version (ADR 0019).
  • @spotcraft/kit and the spotcraft package are deprecated on npm, pointing to their replacements. They are not removed.

Consequences

  • One tag releases Spotcraft again. The kit's separate tags and release check go away.
  • spotkit can change without a Spotcraft release, and a Spotcraft release never forces an app upgrade. The contract between them is docs/contracts.md, not a shared package.
  • Nuxt and TanStack Start apps write a few lines of glue themselves, which the adapters used to hold.
  • sokobanko and vinskiano switch packages once.

Clone this wiki locally