Repository navigation
ADR 0036
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.
@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.
-
Provisioning moves into the platform:
provisionandpurgelive in the CLI package, as itsspotcraft/provisionexport, 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 WebRequest,ResponseandHeadersonly, and has no framework adapters:-
verifyUser(request)checks a bearer token or session JWT againstAUTH_JWKS_URL; -
guest(request)gets or creates the guest throughAUTH_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 staysspotcraft), with the project's version (ADR 0019). -
@spotcraft/kitand thespotcraftpackage are deprecated on npm, pointing to their replacements. They are not removed.
- 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.
Published from docs/. Edit the files there; changes here are overwritten.