devlyn-cli 0.3.0 → 0.5.0

package/optional-skills/better-auth-setup/references/schema.md

@@ -0,0 +1,224 @@
+# Database Schema Reference
+
+Complete Drizzle ORM schema for Better Auth with multi-tenant organization support, API keys, and usage tracking.
+
+## Table of Contents
+1. [Auth Tables](#auth-tables) — users, sessions, accounts, verifications
+2. [Organization Tables](#organization-tables) — organizations, memberships, invitations
+3. [Project & API Key Tables](#project--api-key-tables) — projects, api_keys
+4. [Supporting Tables](#supporting-tables) — usage, billing, webhooks
+
+## Auth Tables
+
+These tables are managed by Better Auth. Define them in Drizzle with the exact columns Better Auth expects, using your preferred table names (you'll map them in the adapter config).
+
+```typescript
+import {
+  boolean, index, pgTable, text, timestamp,
+  uniqueIndex, uuid, varchar,
+} from "drizzle-orm/pg-core";
+
+// Users — core identity table
+export const users = pgTable("users", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  name: varchar("name", { length: 255 }),
+  email: varchar("email", { length: 255 }).notNull().unique(),
+  emailVerified: boolean("email_verified").notNull().default(false),
+  image: text("image"),
+  createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+});
+
+// Sessions — tracks active login sessions
+export const sessions = pgTable(
+  "sessions",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    userId: uuid("user_id")
+      .notNull()
+      .references(() => users.id, { onDelete: "cascade" }),
+    token: varchar("token", { length: 255 }).notNull().unique(),
+    expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),
+    ipAddress: varchar("ip_address", { length: 45 }),
+    userAgent: text("user_agent"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [index("idx_sessions_user_id").on(table.userId)],
+);
+
+// Accounts — OAuth and credential accounts linked to users
+export const accounts = pgTable(
+  "accounts",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    userId: uuid("user_id")
+      .notNull()
+      .references(() => users.id, { onDelete: "cascade" }),
+    accountId: varchar("account_id", { length: 255 }).notNull(),
+    providerId: varchar("provider_id", { length: 255 }).notNull(),
+    accessToken: text("access_token"),
+    refreshToken: text("refresh_token"),
+    accessTokenExpiresAt: timestamp("access_token_expires_at", { withTimezone: true }),
+    refreshTokenExpiresAt: timestamp("refresh_token_expires_at", { withTimezone: true }),
+    scope: text("scope"),
+    password: text("password"),
+    idToken: text("id_token"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [
+    index("idx_accounts_user_id").on(table.userId),
+    uniqueIndex("idx_accounts_provider").on(table.providerId, table.accountId),
+  ],
+);
+
+// Verifications — email verification and password reset tokens
+export const verifications = pgTable(
+  "verifications",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    identifier: text("identifier").notNull(),
+    value: text("value").notNull(),
+    expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [index("idx_verifications_identifier").on(table.identifier)],
+);
+```
+
+### Key Design Decisions
+
+- **UUIDs everywhere** — Better Auth supports UUID primary keys via `defaultRandom()`. This avoids sequential ID enumeration attacks.
+- **Cascade deletes on sessions/accounts** — When a user is deleted, their sessions and OAuth accounts are automatically cleaned up.
+- **Unique constraint on (providerId, accountId)** — Prevents duplicate OAuth account links.
+- **Index on verifications.identifier** — Email lookups during verification need to be fast.
+- **`withTimezone: true`** — All timestamps stored in UTC. Prevents timezone bugs in multi-region deployments.
+
+## Organization Tables
+
+Multi-tenant support with role-based membership.
+
+```typescript
+export const organizations = pgTable(
+  "organizations",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    name: varchar("name", { length: 255 }).notNull(),
+    slug: varchar("slug", { length: 100 }).notNull().unique(),
+    logo: text("logo"),
+    metadata: text("metadata"),
+    plan: varchar("plan", { length: 50 }).notNull().default("free"),
+    // Billing provider fields (Stripe/Polar/etc.)
+    billingCustomerId: varchar("billing_customer_id", { length: 255 }),
+    billingSubscriptionId: varchar("billing_subscription_id", { length: 255 }),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [index("idx_organizations_billing").on(table.billingCustomerId)],
+);
+
+export const orgMemberships = pgTable(
+  "org_memberships",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    organizationId: uuid("organization_id")
+      .notNull()
+      .references(() => organizations.id, { onDelete: "cascade" }),
+    userId: uuid("user_id")
+      .notNull()
+      .references(() => users.id, { onDelete: "cascade" }),
+    role: varchar("role", { length: 50 }).notNull().default("member"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [
+    uniqueIndex("idx_org_memberships_unique").on(table.organizationId, table.userId),
+    index("idx_org_memberships_user").on(table.userId),
+    index("idx_org_memberships_org").on(table.organizationId),
+  ],
+);
+
+export const invitations = pgTable(
+  "invitations",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    email: varchar("email", { length: 255 }).notNull(),
+    inviterId: uuid("inviter_id")
+      .notNull()
+      .references(() => users.id, { onDelete: "cascade" }),
+    organizationId: uuid("organization_id")
+      .notNull()
+      .references(() => organizations.id, { onDelete: "cascade" }),
+    role: varchar("role", { length: 50 }).notNull().default("member"),
+    status: varchar("status", { length: 50 }).notNull().default("pending"),
+    expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [
+    index("idx_invitations_org").on(table.organizationId),
+    index("idx_invitations_email").on(table.email),
+  ],
+);
+```
+
+### Key Design Decisions
+
+- **Unique (org, user) membership** — A user can only have one role per org.
+- **Plan on organization** — Billing is org-level, not user-level. This simplifies plan enforcement.
+- **Slug is unique** — Used in URLs (`/orgs/my-org`). Auto-generated with UUID suffix to prevent collisions.
+
+## Project & API Key Tables
+
+Projects scope resources within an organization. API keys are scoped to projects.
+
+```typescript
+export const projects = pgTable(
+  "projects",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    organizationId: uuid("organization_id")
+      .notNull()
+      .references(() => organizations.id, { onDelete: "cascade" }),
+    name: varchar("name", { length: 255 }).notNull(),
+    slug: varchar("slug", { length: 100 }).notNull(),
+    description: text("description"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [
+    uniqueIndex("idx_projects_org_slug").on(table.organizationId, table.slug),
+    index("idx_projects_org").on(table.organizationId),
+  ],
+);
+
+export const apiKeys = pgTable(
+  "api_keys",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    projectId: uuid("project_id")
+      .notNull()
+      .references(() => projects.id, { onDelete: "cascade" }),
+    name: varchar("name", { length: 255 }).notNull(),
+    keyHash: varchar("key_hash", { length: 255 }).notNull(),
+    keyPrefix: varchar("key_prefix", { length: 12 }).notNull(),
+    lastUsedAt: timestamp("last_used_at", { withTimezone: true }),
+    expiresAt: timestamp("expires_at", { withTimezone: true }),
+    revokedAt: timestamp("revoked_at", { withTimezone: true }),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [
+    index("idx_api_keys_project").on(table.projectId),
+    uniqueIndex("idx_api_keys_hash").on(table.keyHash),
+    index("idx_api_keys_prefix").on(table.keyPrefix),
+  ],
+);
+```
+
+### Key Design Decisions
+
+- **Project slug unique per org** — Not globally unique, scoped to organization via composite unique index.
+- **keyHash unique** — Enables O(1) lookup during API key validation.
+- **Soft-delete via `revokedAt`** — Revoked keys remain in the database for audit trail. The auth middleware checks `revokedAt !== null` to reject them.
+- **`lastUsedAt` nullable** — Updated fire-and-forget on each API key auth. Useful for usage analytics and stale key detection.
+- **No plaintext key column** — The plaintext is generated, returned to the user once, and only the SHA-256 hash is stored. This is a security requirement, not an optimization.

package/optional-skills/better-auth-setup/references/testing.md

@@ -0,0 +1,241 @@
+# Test Infrastructure Reference
+
+Test setup, seed factories, and integration test patterns for Better Auth with Bun.
+
+## Table of Contents
+1. [Test Preload](#test-preload)
+2. [Seed Data Factory](#seed-data-factory)
+3. [Integration Test App](#integration-test-app)
+4. [Database Cleanup](#database-cleanup)
+5. [Key Testing Patterns](#key-testing-patterns)
+
+## Test Preload
+
+Prevents the most common testing pitfall: real emails sent during test runs.
+
+```typescript
+// src/test-utils/setup.ts — preloaded via bunfig.toml
+// Without this, test signups send real emails through Resend
+// when RESEND_API_KEY is in your .env file.
+process.env.NODE_ENV = "test";
+process.env.RESEND_API_KEY = ""; // Force email to console-log fallback
+
+// Bridge test database — use a separate DB for tests
+if (process.env.TEST_DATABASE_URL) {
+  process.env.DATABASE_URL = process.env.TEST_DATABASE_URL;
+}
+```
+
+```toml
+# bunfig.toml
+[test]
+preload = ["./src/test-utils/setup.ts"]
+```
+
+**Why preload?** Bun's preload runs before any test file imports. This guarantees that config validation (which runs at import time) sees the correct environment variables. Setting `RESEND_API_KEY = ""` before any module loads ensures the email module's lazy client never initializes.
+
+## Seed Data Factory
+
+Creates a complete tenant hierarchy for integration tests. Every call produces unique identifiers to prevent collisions in parallel test runs.
+
+```typescript
+// src/test-utils/db.ts
+import { db } from "../db";
+import {
+  organizations, users, orgMemberships,
+  projects, apiKeys, sessions, accounts,
+  verifications, invitations,
+} from "../db/schema";
+
+export async function seedTestData() {
+  const uniqueSuffix = `${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
+
+  // Create org → user → membership → project → API key
+  const [org] = await db.insert(organizations).values({
+    name: `Test Org ${uniqueSuffix}`,
+    slug: `test-org-${uniqueSuffix}`,
+    plan: "free",
+  }).returning();
+
+  const [user] = await db.insert(users).values({
+    email: `test-${uniqueSuffix}@example.com`,
+    name: "Test User",
+    emailVerified: true,
+  }).returning();
+
+  await db.insert(orgMemberships).values({
+    organizationId: org.id,
+    userId: user.id,
+    role: "owner",
+  });
+
+  const [project] = await db.insert(projects).values({
+    organizationId: org.id,
+    name: `Test Project ${uniqueSuffix}`,
+    slug: `test-project-${uniqueSuffix}`,
+  }).returning();
+
+  // Generate API key
+  const { key, hash, prefix } = await generateTestApiKey();
+  const [apiKey] = await db.insert(apiKeys).values({
+    projectId: project.id,
+    name: "Test Key",
+    keyHash: hash,
+    keyPrefix: prefix,
+  }).returning();
+
+  return { org, user, project, apiKey, plaintextKey: key };
+}
+
+// Helper: generate a test API key
+async function generateTestApiKey() {
+  const { API_KEY_PREFIX, base62Encode, hashKey } = await import("../lib/api-keys");
+  const randomBytes = crypto.getRandomValues(new Uint8Array(32));
+  const key = API_KEY_PREFIX + base62Encode(randomBytes);
+  const hash = await hashKey(key);
+  const prefix = key.slice(0, 12);
+  return { key, hash, prefix };
+}
+```
+
+**Key design decisions:**
+- `uniqueSuffix` uses `Date.now()` + random chars for collision-free parallel tests
+- `emailVerified: true` so tests don't need to go through email verification flow
+- Returns `plaintextKey` so tests can immediately make authenticated requests
+
+## Integration Test App
+
+Builds the full middleware chain matching production. This catches middleware ordering bugs before they reach production.
+
+```typescript
+// src/test-utils/app.ts
+import { Hono } from "hono";
+
+// Lazy imports to avoid circular dependency issues during test setup
+export function createIntegrationApp() {
+  const { authMiddleware } = require("../middleware/auth");
+  const { tenantContextMiddleware } = require("../middleware/tenant-context");
+  const { rateLimitMiddleware } = require("../middleware/rate-limit");
+
+  const app = new Hono();
+
+  // Request ID
+  app.use("*", async (c, next) => {
+    c.set("requestId", crypto.randomUUID());
+    await next();
+  });
+
+  // Auth → Tenant Context → Rate Limit (same order as production)
+  app.use("*", authMiddleware);
+  app.use("*", tenantContextMiddleware);
+  app.use("*", rateLimitMiddleware);
+
+  // Mount route handlers here...
+  return app;
+}
+```
+
+**Why lazy imports?** The auth module imports the database module, which reads `DATABASE_URL` from the environment. If imported eagerly at the top level, the test preload script might not have run yet, causing config validation to fail.
+
+## Database Cleanup
+
+Delete tables in FK dependency order to avoid constraint violations.
+
+```typescript
+// Clean tables in FK dependency order
+export async function cleanupDatabase() {
+  // Children first, parents last
+  await db.delete(apiKeys);
+  await db.delete(projects);
+  await db.delete(orgMemberships);
+  await db.delete(sessions);
+  await db.delete(accounts);
+  await db.delete(verifications);
+  await db.delete(invitations);
+  await db.delete(organizations);
+  await db.delete(users);
+}
+```
+
+**Order matters.** If you try to delete `organizations` before `projects`, the FK constraint on `projects.organization_id` will reject the delete. Start from leaf tables and work toward root tables.
+
+## Key Testing Patterns
+
+### Test Auth via API Key
+
+```typescript
+import { describe, test, expect, beforeAll, afterAll } from "bun:test";
+
+describe("Protected endpoint", () => {
+  let testData: Awaited<ReturnType<typeof seedTestData>>;
+
+  beforeAll(async () => {
+    testData = await seedTestData();
+  });
+
+  afterAll(async () => {
+    await cleanupDatabase();
+  });
+
+  test("returns 200 with valid API key", async () => {
+    const app = createIntegrationApp();
+    const res = await app.request("/v1/endpoint", {
+      headers: {
+        Authorization: `Bearer ${testData.plaintextKey}`,
+      },
+    });
+    expect(res.status).toBe(200);
+  });
+
+  test("returns 401 without auth", async () => {
+    const app = createIntegrationApp();
+    const res = await app.request("/v1/endpoint");
+    expect(res.status).toBe(401);
+  });
+});
+```
+
+### Test Signup Flow
+
+```typescript
+test("signup creates user and personal org", async () => {
+  const res = await app.request("/auth/sign-up/email", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      email: `signup-test-${Date.now()}@example.com`,
+      password: "secure-password-123",
+      name: "Test User",
+    }),
+  });
+
+  expect(res.status).toBe(200);
+
+  // Verify auto-org creation via databaseHooks
+  const user = await db.select().from(users)
+    .where(eq(users.email, email)).limit(1);
+
+  const membership = await db.select().from(orgMemberships)
+    .where(eq(orgMemberships.userId, user[0].id)).limit(1);
+
+  expect(membership).toHaveLength(1);
+  expect(membership[0].role).toBe("owner");
+});
+```
+
+### Test Tenant Isolation
+
+```typescript
+test("cannot access resources from another org", async () => {
+  const org1 = await seedTestData();
+  const org2 = await seedTestData();
+
+  // Use org1's API key to try accessing org2's project
+  const res = await app.request(`/v1/projects/${org2.project.id}`, {
+    headers: { Authorization: `Bearer ${org1.plaintextKey}` },
+  });
+
+  // Should be 404 (not 403, to prevent ID enumeration)
+  expect(res.status).toBe(404);
+});
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devlyn-cli",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Claude Code configuration toolkit for teams",
   "bin": {
     "devlyn": "bin/devlyn.js"
@@ -8,6 +8,7 @@
   "files": [
     "bin",
     "config",
+    "optional-commands",
     "optional-skills",
     "CLAUDE.md"
   ],