| name | holeauth-compat-matrix |
| description | Generate a timestamped holeauth compatibility matrix as a Markdown report under docs/compat/. Produces two tables: (1) Feature × Framework (Next.js App Router, Next.js Pages Router, Express, Hono) and (2) Drizzle Adapter × Database (Postgres, MySQL, SQLite). Use when: auditing holeauth support status, generating KPI snapshot, tracking compatibility roadmap, reviewing which features work where, compatibility report, support matrix. |
| argument-hint | Optional: output folder (default: docs/compat) |
Holeauth Compatibility Matrix
Produces a timestamped Markdown file at docs/compat/YYYY-MM-DD.md (or a custom path) containing two compatibility tables derived by reading the live source of all packages in the monorepo.
When to Use
- Periodic KPI snapshots for the roadmap
- Before a release — confirm no regressions
- After adding a new framework adapter or plugin
Procedure
Step 1 — Resolve Output Path
Use today's date (YYYY-MM-DD) and write to:
docs/compat/YYYY-MM-DD.md
If the docs/compat/ directory doesn't exist, create it. Never overwrite an existing file; append a -2, -3 suffix if the date file already exists.
Step 2 — Scan Packages
For every folder under packages/ in the monorepo root, read in parallel:
| What to read | Where to find it |
|---|
| Package name + version | package.json → name, version |
| Peer dependencies | package.json → peerDependencies |
| Main exports / subpath exports | package.json → exports |
| Source entry | src/index.ts (primary), src/ directory listing as fallback |
For each package, determine:
- Framework target: Look at the package name and source imports. Server framework packages:
nextjs-app-router (imports next/headers, next/navigation, next/server), nextjs-pages-router (imports next types like NextApiRequest, GetServerSidePropsContext), express (imports from express), hono (imports from hono). Headless: pure TS/JS with no framework imports.
- Feature set: Which auth flows, endpoints, or utilities does the source export? Look for:
signin, register, password-reset, invite, twofa, passkey, rbac, idp, session, middleware, sso, refresh, audit.
- Database support: Does the package have subpath exports
./pg, ./mysql, ./sqlite? List which ones exist as actual source folders.
- Edge safety: Does the package use
fs, path, child_process, or @node-rs/*? → Not edge-safe.
Packages to cover (minimum set):
core, nextjs-app-router, nextjs-pages-router, express, hono, react, react-ui, trpc,
plugin-2fa, plugin-passkey, plugin-rbac, plugin-idp,
adapter-drizzle, 2fa-drizzle, passkey-drizzle, rbac-drizzle, idp-drizzle,
rbac-yaml
Step 3 — Build Matrix 1: Feature × Framework
Columns: Next.js App Router | Next.js Pages Router | Express | Hono
Use these symbol conventions:
| Symbol | Meaning |
|---|
| ✅ | First-class support, officially wired |
| ⚠️ | Works but requires manual wiring / no official adapter |
| ❌ | Not supported / architecturally blocked |
| – | Not applicable |
Feature rows (group by section):
Setup & Routing
- Auth instance (
createAuthHandler / createPagesAuthHandler / createExpressAuth / createHonoAuth)
- Route handler (catch-all dispatcher)
- Framework middleware (Next.js middleware / Express middleware / Hono middleware)
Authentication
- Email + Password — Login
- Email + Password — Registration
- Password Reset Flow
- Email Verification
- Invite System
Session
- JWT Access + Refresh Rotation
- Server-side Session (RSC / SSR)
- Client-side Session (
useSession)
2FA / TOTP
- TOTP Enrollment + Verify
- Recovery Codes
- QR Code Generation
- Rate Limiting (in-memory)
Passkeys (WebAuthn)
- Passkey Registration
- Passkey Login
- Credential Management (list/delete)
RBAC
- Roles + Permissions (wildcard)
- Group Inheritance
- Direct User Permission Overrides
- Permission Cache (TTL)
- RBAC YAML Configuration
- Client RBAC Snapshot (
useRbac)
SSO — Consumer
- OAuth Provider: Google
- OAuth Provider: GitHub
- OAuth Provider: Discord
- OAuth Provider: Microsoft
- Generic OIDC Consumer
IDP Server (OAuth2/OIDC)
- Discovery
/.well-known/openid-configuration
- JWKS Endpoint
- Authorization Code + PKCE
- Refresh Token Rotation (family-revoke)
- Token Revocation (RFC 7009)
- RP-initiated Logout
- Consent Management
- Signing Key Rotation (RS256)
- Teams / App Registry
tRPC Integration
- Auth Context (
createHoleauthContext)
- Transparent Token Refresh
- RBAC Permission Guard
Headless UI
SignInForm / SignUpFormPasswordResetRequestForm / PasswordChangeFormTwoFactorVerifyFormPasskeySetup / PasskeyLoginButtonSsoButton / SignOutButton
Infrastructure
- Audit Log
- Edge Runtime compatible
Rating rules for each cell — derived from Step 2 analysis:
- A feature is ✅ for a framework only if the source is wired end-to-end for that framework (no manual adapter needed).
- A feature is ⚠️ if the plugin/core is headless and could work in that framework but no official adapter/wrapper exists, OR if the framework binding requires user-supplied glue (e.g., headless UI in non-React frameworks).
- A feature is ❌ if the implementation imports a framework-specific API incompatible with that target (e.g.,
next/headers → blocked in Pages Router, Express, and Hono).
- Use – when the concept does not apply (e.g., React
useSession hook in Express / Hono SSR).
- For headless UI components (React): mark ✅ for App Router and Pages Router (both render React), and – for Express / Hono (server-only frameworks).
Step 4 — Build Matrix 2: Drizzle Adapter × Database
Columns: Postgres | MySQL | SQLite
Rows: each Drizzle adapter package. A cell is ✅ if a source folder (src/pg/, src/mysql/, src/sqlite/) exists and is non-empty; ❌ otherwise.
Step 5 — Build Roadmap Gap Table
Add a third table: Roadmap Implications. Columns: Priority (🔴/🟡/🟢), Gap, Impact. Derive from any ❌ cells in Matrix 1 that represent a high-value framework+feature combination.
Priority rules:
- 🔴 High: Gap blocks adoption in a major ecosystem (e.g., a feature missing in 2+ of the 4 framework columns, non-Postgres IDP)
- 🟡 Medium: Gap limits a specific integration path (e.g., generic OIDC consumer in only one framework)
- 🟢 Low: Nice-to-have or niche
Step 6 — Write the Report
Assemble the report with this exact structure:
# Holeauth Compatibility Matrix — YYYY-MM-DD
> Auto-generated by the `holeauth-compat-matrix` skill. All data derived from live monorepo source.
> All packages: vX.Y.Z-alpha.N
## Legend
| Symbol | Meaning |
|---|---|
| ✅ | First-class support |
| ⚠️ | Works, manual wiring required |
| ❌ | Not supported |
| – | Not applicable |
## Matrix 1 — Feature × Framework
<table from Step 3>
## Matrix 2 — Drizzle Adapter × Database
<table from Step 4>
## Roadmap Gaps
<table from Step 5>
## Package Inventory
<one-line-per-package summary: name | version | framework target | headless | edge-safe>
Write the file using create_file. Do NOT overwrite existing files.
After writing, output the file path and a brief summary of the most critical gaps found.
Quality Criteria
The report is complete when:
