@next-starters/skill-auth-org-onboarding
v1.0.0
Published
Scaffolds the auto-create-or-join-org-on-first-login flow that closes a real, independently-observed product gap: a brand-new signup with zero org membership hits a 403/no-access wall on every…
Readme
auth-org-onboarding
Scaffold the auto-create-or-join-org-on-first-login flow that closes the "new signup lands on a 403/no-access page" gap. Not part of the auth-email/auth-transactional-emails pattern — a separate, follow-up skill for the signup-adjacent gap those two don't cover.
Inputs
--org-resolution <live-db|jwt-embedded>— required, no default; the scaffolder rejects a missing or unrecognized value before writing any file. Picks which of two genuinely different, non-interchangeable architectures your repo needs:live-db— org membership resolved via a fresh DB lookup on every request. No JWT claim, no session-refresh step.jwt-embedded— org id/role minted into the JWT via a Supabase Auth Access Token Hook. Requires an explicit session-refresh step after onboarding.- Not sure which one your repo needs? Check for a
custom_access_token_hookfunction registered in your Supabase project's Auth settings — if it exists, you'rejwt-embedded; if org membership is just a normal table your API queries per request, you'relive-db.
- (jwt-embedded only)
--users-table,--user-roles-table,--role-claim-key— table/column names substituted intoaccess-token-hook.sql's tokens (defaults:users,user_roles,role).
What it does
- Scaffolds exactly ONE variant's file set into
<out>/<dir>/viabin/add-auth-org-onboarding.mjs— write-by-default,--dry-runto preview, never overwrites,--org-resolutionvalidated before any write. - Encodes the invariants that keep both variants correct (see
SKILL.md): the required no-default flag, idempotent-check-first, advisory-lock race protection (grafted onto jwt-embedded as the one deliberate deviation from its ported source, which lacks it), an already-correct, faithfully-ported slug/name uniquification pattern for both (unit-tested directly), the Access Token Hook's deny-by-default fallback plus its RLS-policy and null-safe-claim-merge requirements, the two non-interchangeable session-refresh mechanisms, and live-db's no-refresh-needed self-heal. - Ships two complete reference route implementations (one per variant), a shared, unit-tested uniquification helper, one Access Token Hook SQL function, and two web-integration snippets — never mixed across variants in a single scaffold run.
Scaffold directly
# live-db variant
node bin/add-auth-org-onboarding.mjs --org-resolution live-db
# jwt-embedded variant, with real table/column names
node bin/add-auth-org-onboarding.mjs \
--org-resolution jwt-embedded \
--users-table app_users \
--user-roles-table app_memberships \
--role-claim-key workspace_roleAdd --dry-run to preview, --dir <name> to change the output
subdirectory (default org-onboarding), --out <dir> to target a repo
other than the cwd. It refuses to overwrite existing files and exits
non-zero (writing nothing) if --org-resolution is omitted or invalid.
After scaffolding:
- Port the copied reference route into your own API framework/route registration — keep the transaction/lock/uniquify logic close to verbatim, only the framework glue should change.
- (jwt-embedded only) Apply
access-token-hook.sqlas a migration AFTER your users/user_roles-equivalent tables exist, then register it as a Supabase Auth Access Token Hook in the project's Auth settings. - Wire the matching web-integration reference into your authenticated shell — for jwt-embedded, pick the ONE session-refresh mechanism that matches your actual auth stack (direct Supabase vs. a framework like NextAuth in front of it); they are not interchangeable.
Install globally
Symlink into your global skills the same way as the other next-starters skills:
skills add [email protected]:catesandrew/next-starters.git \
--skill skills/auth-org-onboarding -gLayout
auth-org-onboarding/
SKILL.md the invariants + red flags + references
metadata.json
references/
onboarding-live-db.reference.ts live-db route (idempotent, advisory lock, uniquify)
onboarding-jwt-embedded.reference.ts jwt-embedded route (+ grafted advisory lock)
org-uniquify.example.ts shared uniquify helper (unit-tested)
access-token-hook.sql jwt-embedded only — Supabase Access Token Hook
web-integration-live-db.reference.tsx silent server-layout self-heal
web-integration-jwt-embedded.reference.tsx /welcome bootstrap + both refresh mechanismsThe scaffolder lives at next-starters/bin/add-auth-org-onboarding.mjs.
