@opensaas/stack-cli 0.5.0 → 0.6.0

package/CLAUDE.md

@@ -1,298 +0,0 @@
-# @opensaas/stack-cli
-
-Command-line tools for OpenSaas Stack providing code generation and development utilities.
-
-## Purpose
-
-Converts `opensaas.config.ts` into Prisma schema and TypeScript types. Provides watch mode for automatic regeneration during development.
-
-## Key Files & Commands
-
-### Binary (`bin/opensaas.js`)
-
-Entry point exposing `opensaas` CLI command
-
-### Commands (`src/commands/`)
-
-- `generate.ts` - One-time generation
-- `dev.ts` - Watch mode with automatic regeneration
-- `init.ts` - Project scaffolding (future)
-
-### Generators (`src/generator/`)
-
-- `prisma.ts` - Generates `prisma/schema.prisma` from config
-- `types.ts` - Generates `.opensaas/types.ts` TypeScript types
-- `context.ts` - Generates `.opensaas/context.ts` context factory
-- `mcp.ts` - Generates MCP tools metadata
-- `type-patcher.ts` - Patches Prisma types for relationships
-
-## Architecture
-
-### Config Loading
-
-Uses `jiti` to execute TypeScript config:
-
-```typescript
-const jiti = createJiti(import.meta.url)
-const config = jiti('./opensaas.config.ts').default
-```
-
-### Generator Pipeline
-
-1. Load config from `opensaas.config.ts`
-2. Generate Prisma schema → `prisma/schema.prisma`
-3. Generate TypeScript types → `.opensaas/types.ts`
-4. Generate context factory → `.opensaas/context.ts`
-5. Generate MCP tools (if enabled) → `.opensaas/mcp-tools.json`
-
-### Watch Mode
-
-Uses `chokidar` to watch `opensaas.config.ts`:
-
-```typescript
-const watcher = chokidar.watch('opensaas.config.ts')
-watcher.on('change', () => runGenerator())
-```
-
-## CLI Usage
-
-### Generate Command
-
-```bash
-opensaas generate
-```
-
-Outputs:
-
-- `✅ Prisma schema generated`
-- `✅ TypeScript types generated`
-- Next steps (run `prisma generate` and `db push`)
-
-### Dev Command
-
-```bash
-opensaas dev
-```
-
-Outputs:
-
-- Initial generation
-- `👀 Watching opensaas.config.ts for changes...`
-- Auto-regenerates on file changes
-
-## Generated Files
-
-### Prisma Schema (`prisma/schema.prisma`)
-
-```prisma
-datasource db {
-  provider = "sqlite"
-}
-
-generator client {
-  provider = "prisma-client"
-}
-
-model Post {
-  id String @id @default(cuid())
-  title String
-  createdAt DateTime @default(now())
-  updatedAt DateTime @updatedAt
-}
-```
-
-**Note:** Prisma 7 no longer includes `url` in the schema. The database URL is passed to PrismaClient via adapters in the `prismaClientConstructor` function.
-
-### Prisma CLI Config (`prisma.config.ts`)
-
-```typescript
-import 'dotenv/config'
-import { defineConfig, env } from 'prisma/config'
-
-export default defineConfig({
-  schema: 'prisma/schema.prisma',
-  datasource: {
-    url: env('DATABASE_URL'),
-  },
-})
-```
-
-**Purpose:** Prisma 7 requires this file at the project root for CLI commands like `prisma db push` and `prisma migrate dev` to work. This is separate from the runtime configuration.
-
-**Key points:**
-
-- Generated automatically by `opensaas generate`
-- Requires `dotenv` package to load `.env` files
-- Reads `DATABASE_URL` from environment variables
-- Only used by Prisma CLI commands, not by application runtime
-
-### Types (`.opensaas/types.ts`)
-
-```typescript
-export type Post = {
-  id: string
-  title: string
-  createdAt: Date
-  updatedAt: Date
-}
-
-export type PostCreateInput = {
-  title: string
-}
-
-export type PostUpdateInput = {
-  title?: string
-}
-```
-
-### Context Factory (`.opensaas/context.ts`)
-
-```typescript
-import { createContext } from '@opensaas/stack-core'
-import { PrismaClient } from '@prisma/client'
-import config from '../opensaas.config'
-
-// Prisma 7 requires adapters - PrismaClient created via prismaClientConstructor
-const prisma = config.db.prismaClientConstructor(PrismaClient)
-
-export function getContext(session?: any) {
-  return createContext(config, prisma, session)
-}
-```
-
-**Note:** The actual generated context is more sophisticated with async config resolution and singleton management, but this shows the core pattern.
-
-## Integration Points
-
-### With @opensaas/stack-core
-
-- Imports generator functions from core
-- Delegates Prisma/TS generation to field methods via core
-
-### With @opensaas/stack-auth
-
-- Context factory supports custom `prismaClientConstructor` for Better-auth session provider
-
-### With MCP (Model Context Protocol)
-
-- Generates MCP tools metadata when MCP enabled in config
-- MCP functionality is now in `@opensaas/stack-core/mcp` (runtime) and `@opensaas/stack-auth/mcp` (adapter)
-
-### With Prisma
-
-Workflow:
-
-1. `opensaas generate` → creates `prisma/schema.prisma` and `prisma.config.ts`
-2. `npx prisma generate` → creates Prisma Client
-3. `npx prisma db push` → pushes schema to database (uses `prisma.config.ts` for datasource URL)
-
-## Common Patterns
-
-### Development Workflow
-
-```bash
-# Terminal 1: Watch and regenerate
-opensaas dev
-
-# Terminal 2: Run Next.js
-pnpm next dev
-
-# Edit opensaas.config.ts - auto regenerates!
-```
-
-### Package.json Scripts
-
-```json
-{
-  "scripts": {
-    "generate": "opensaas generate",
-    "db:push": "prisma db push",
-    "db:studio": "prisma studio",
-    "dev": "opensaas dev"
-  }
-}
-```
-
-### CI/CD Integration
-
-```yaml
-- run: pnpm install
-- run: opensaas generate
-- run: npx prisma generate
-- run: pnpm test
-```
-
-### Custom Prisma Client (Required in Prisma 7)
-
-**All configs must provide `prismaClientConstructor`** with a database adapter:
-
-```typescript
-// SQLite example
-import { PrismaBetterSQLite3 } from '@prisma/adapter-better-sqlite3'
-import Database from 'better-sqlite3'
-
-config({
-  db: {
-    provider: 'sqlite',
-    url: process.env.DATABASE_URL || 'file:./dev.db',
-    prismaClientConstructor: (PrismaClient) => {
-      const db = new Database(process.env.DATABASE_URL || './dev.db')
-      const adapter = new PrismaBetterSQLite3(db)
-      return new PrismaClient({ adapter })
-    },
-  },
-})
-```
-
-```typescript
-// PostgreSQL example
-import { PrismaPg } from '@prisma/adapter-pg'
-import pg from 'pg'
-
-config({
-  db: {
-    provider: 'postgresql',
-    url: process.env.DATABASE_URL,
-    prismaClientConstructor: (PrismaClient) => {
-      const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL })
-      const adapter = new PrismaPg(pool)
-      return new PrismaClient({ adapter })
-    },
-  },
-})
-```
-
-Generated context always uses the constructor:
-
-```typescript
-// .opensaas/context.ts
-const prisma = config.db.prismaClientConstructor(PrismaClient)
-```
-
-## Type Patching
-
-CLI patches Prisma types for relationship fields to handle access control:
-
-- Relationships can be `null` when access denied
-- Adds `| null` to relationship field types in generated types
-
-## Error Handling
-
-Common errors:
-
-- Config not found → check file exists in CWD
-- TypeScript errors in config → fix syntax in `opensaas.config.ts`
-- Permission denied → ensure write access to `prisma/` and `.opensaas/`
-
-## Output Styling
-
-Uses `chalk` and `ora` for colored, animated output:
-
-- ✅ Green checkmarks for success
-- ❌ Red X for errors
-- 🚀 Emoji for branding
-- Spinner animations during generation
-
-## Future Commands
-
-`opensaas init` - Project scaffolding with templates (planned)

package/src/commands/__snapshots__/generate.test.ts.snap

@@ -1,413 +0,0 @@
-// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
-
-exports[`Generate Command Integration > Generator Integration > should generate all files for a basic config > context 1`] = `
-"/**
- * Auto-generated context factory
- *
- * This module provides a simple API for creating OpenSaas contexts.
- * It abstracts away Prisma client management and configuration.
- *
- * DO NOT EDIT - This file is automatically generated by 'pnpm generate'
- */
-
-import { getContext as getOpensaasContext } from '@opensaas/stack-core'
-import type { Session as OpensaasSession, OpenSaasConfig } from '@opensaas/stack-core'
-import { PrismaClient } from './prisma-client/client'
-import type { Context } from './types'
-import { prismaExtensions } from './prisma-extensions'
-import configOrPromise from '../opensaas.config'
-
-// Resolve config if it's a Promise (when plugins are present)
-const configPromise = Promise.resolve(configOrPromise)
-let resolvedConfig: OpenSaasConfig | null = null
-
-// Internal Prisma singleton - managed automatically
-const globalForPrisma = globalThis as unknown as { prisma: ReturnType<typeof createExtendedPrisma> | null }
-let prisma: ReturnType<typeof createExtendedPrisma> | null = null
-
-/**
- * Create Prisma client with result extensions
- */
-function createExtendedPrisma(basePrisma: PrismaClient) {
-  // Check if there are any extensions to apply
-  if (Object.keys(prismaExtensions).length === 0) {
-    return basePrisma
-  }
-  // Apply result extensions
-  return basePrisma.$extends(prismaExtensions)
-}
-
-async function getPrisma() {
-  if (!prisma) {
-    if (!resolvedConfig) {
-      resolvedConfig = await configPromise
-    }
-    const basePrisma = resolvedConfig.db.prismaClientConstructor!(PrismaClient)
-    const extendedPrisma = createExtendedPrisma(basePrisma)
-    prisma = globalForPrisma.prisma ?? extendedPrisma
-    if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma
-  }
-  return prisma
-}
-
-async function getConfig() {
-  if (!resolvedConfig) {
-    resolvedConfig = await configPromise
-  }
-  return resolvedConfig
-}
-
-/**
- * Storage utilities (not configured)
- */
-const storage = {
-  uploadFile: async () => {
-    throw new Error('Storage is not configured. Add storage providers to your opensaas.config.ts')
-  },
-  uploadImage: async () => {
-    throw new Error('Storage is not configured. Add storage providers to your opensaas.config.ts')
-  },
-  deleteFile: async () => {
-    throw new Error('Storage is not configured. Add storage providers to your opensaas.config.ts')
-  },
-  deleteImage: async () => {
-    throw new Error('Storage is not configured. Add storage providers to your opensaas.config.ts')
-  },
-}
-
-/**
- * Get OpenSaas context with optional session
- *
- * @param session - Optional session object (structure defined by your application)
- *
- * @example
- * \`\`\`typescript
- * // Anonymous access
- * const context = await getContext()
- * const posts = await context.db.post.findMany()
- *
- * // Authenticated access
- * const context = await getContext({ userId: 'user-123' })
- * const myPosts = await context.db.post.findMany()
- *
- * // With custom session type
- * type CustomSession = { userId: string; email: string; role: string } | null
- * const context = await getContext<CustomSession>({ userId: '123', email: 'user@example.com', role: 'admin' })
- * // context.session is now typed as CustomSession
- * \`\`\`
- */
-export async function getContext<TSession extends OpensaasSession = OpensaasSession>(session?: TSession): Promise<Context<TSession>> {
-  const config = await getConfig()
-  const prismaClient = await getPrisma()
-  return getOpensaasContext(config, prismaClient, session ?? null, storage) as unknown as Context<TSession>
-}
-
-/**
- * Raw context for synchronous initialization (e.g., Better-auth setup)
- * This is only available after config is resolved, use with caution
- */
-export const rawOpensaasContext = (async () => {
-  const config = await getConfig()
-  const prismaClient = await getPrisma()
-  return getOpensaasContext(config, prismaClient, null, storage) as unknown as Context
-})()
-
-/**
- * Re-export resolved config for use in admin pages and server actions
- * This is a promise that resolves to the config
- */
-export const config = getConfig()
-"
-`;
-
-exports[`Generate Command Integration > Generator Integration > should generate all files for a basic config > prisma-schema 1`] = `
-"generator client {
-  provider = "prisma-client"
-  output   = "../.opensaas/prisma-client"
-}
-
-datasource db {
-  provider = "sqlite"
-}
-
-model User {
-  id        String   @id @default(cuid())
-  name         String
-  email        String
-  createdAt DateTime @default(now())
-  updatedAt DateTime @updatedAt
-}
-"
-`;
-
-exports[`Generate Command Integration > Generator Integration > should generate all files for a basic config > types 1`] = `
-"/**
- * Generated types from OpenSaas configuration
- * DO NOT EDIT - This file is automatically generated
- */
-
-import type { Session as OpensaasSession, StorageUtils, ServerActionProps, AccessControlledDB, AccessContext } from '@opensaas/stack-core'
-import type { PrismaClient, Prisma } from './prisma-client/client'
-import type { PluginServices } from './plugin-types'
-
-/**
- * Virtual fields for User - computed fields not in database
- * These are added to query results via resolveOutput hooks
- */
-export type UserVirtualFields = {
-  // No virtual fields defined
-}
-
-/**
- * Transformed fields for User - fields with resultExtension transformations
- * These override Prisma's base types with transformed types via result extensions
- */
-export type UserTransformedFields = {
-  // No transformed fields defined
-}
-
-export type UserOutput = {
-  id: string
-  name: string
-  email: string
-  createdAt: Date
-  updatedAt: Date
-} & UserVirtualFields
-
-export type User = UserOutput
-
-export type UserCreateInput = {
-  name: string
-  email: string
-}
-
-export type UserUpdateInput = {
-  name?: string
-  email?: string
-}
-
-export type UserWhereInput = {
-  id?: string
-  AND?: Array<UserWhereInput>
-  OR?: Array<UserWhereInput>
-  NOT?: UserWhereInput
-  name?: { equals?: string, not?: string }
-  email?: { equals?: string, not?: string }
-}
-
-/**
- * Hook types for User list
- * Properly typed to use Prisma's generated input types
- */
-export type UserHooks = {
-  resolveInput?: (args:
-    | {
-        operation: 'create'
-        resolvedData: Prisma.UserCreateInput
-        item: undefined
-        context: import('@opensaas/stack-core').AccessContext
-      }
-    | {
-        operation: 'update'
-        resolvedData: Prisma.UserUpdateInput
-        item: User
-        context: import('@opensaas/stack-core').AccessContext
-      }
-  ) => Promise<Prisma.UserCreateInput | Prisma.UserUpdateInput>
-  validateInput?: (args: {
-    operation: 'create' | 'update'
-    resolvedData: Prisma.UserCreateInput | Prisma.UserUpdateInput
-    item?: User
-    context: import('@opensaas/stack-core').AccessContext
-    addValidationError: (msg: string) => void
-  }) => Promise<void>
-  beforeOperation?: (args: {
-    operation: 'create' | 'update' | 'delete'
-    resolvedData?: Prisma.UserCreateInput | Prisma.UserUpdateInput
-    item?: User
-    context: import('@opensaas/stack-core').AccessContext
-  }) => Promise<void>
-  afterOperation?: (args: {
-    operation: 'create' | 'update' | 'delete'
-    resolvedData?: Prisma.UserCreateInput | Prisma.UserUpdateInput
-    item?: User
-    context: import('@opensaas/stack-core').AccessContext
-  }) => Promise<void>
-}
-
-/**
- * Custom DB type that uses Prisma's conditional types with virtual and transformed field support
- * Types change based on select/include - relationships only present when explicitly included
- * Virtual fields and transformed fields are added to the base model type
- */
-export type CustomDB = Omit<AccessControlledDB<PrismaClient>, 
-  'user'
-> & {
-  user: {
-    findUnique: <T extends Prisma.UserFindUniqueArgs>(
-      args: Prisma.SelectSubset<T, Prisma.UserFindUniqueArgs>
-    ) => Promise<(Omit<Prisma.UserGetPayload<T>, keyof UserTransformedFields> & UserTransformedFields & UserVirtualFields) | null>
-    findMany: <T extends Prisma.UserFindManyArgs>(
-      args?: Prisma.SelectSubset<T, Prisma.UserFindManyArgs>
-    ) => Promise<Array<Omit<Prisma.UserGetPayload<T>, keyof UserTransformedFields> & UserTransformedFields & UserVirtualFields>>
-    create: <T extends Prisma.UserCreateArgs>(
-      args: Prisma.SelectSubset<T, Prisma.UserCreateArgs>
-    ) => Promise<Omit<Prisma.UserGetPayload<T>, keyof UserTransformedFields> & UserTransformedFields & UserVirtualFields>
-    update: <T extends Prisma.UserUpdateArgs>(
-      args: Prisma.SelectSubset<T, Prisma.UserUpdateArgs>
-    ) => Promise<(Omit<Prisma.UserGetPayload<T>, keyof UserTransformedFields> & UserTransformedFields & UserVirtualFields) | null>
-    delete: <T extends Prisma.UserDeleteArgs>(
-      args: Prisma.SelectSubset<T, Prisma.UserDeleteArgs>
-    ) => Promise<(Omit<Prisma.UserGetPayload<T>, keyof UserTransformedFields> & UserTransformedFields & UserVirtualFields) | null>
-    count: (args?: Prisma.UserCountArgs) => Promise<number>
-  }
-}
-
-/**
- * Context type compatible with AccessContext but with CustomDB for virtual field typing
- * Extends AccessContext and overrides db property to include virtual fields in output types
- */
-export type Context<TSession extends OpensaasSession = OpensaasSession> = Omit<AccessContext<PrismaClient>, 'db' | 'session'> & {
-  db: CustomDB
-  session: TSession
-  serverAction: (props: ServerActionProps) => Promise<unknown>
-  sudo: () => Context<TSession>
-}"
-`;
-
-exports[`Generate Command Integration > Generator Integration > should generate consistent output across multiple runs > consistent-output 1`] = `
-"generator client {
-  provider = "prisma-client"
-  output   = "../.opensaas/prisma-client"
-}
-
-datasource db {
-  provider = "sqlite"
-}
-
-model User {
-  id        String   @id @default(cuid())
-  name         String?
-  createdAt DateTime @default(now())
-  updatedAt DateTime @updatedAt
-}
-"
-`;
-
-exports[`Generate Command Integration > Generator Integration > should handle different database providers > mysql-provider 1`] = `
-"generator client {
-  provider = "prisma-client"
-  output   = "../.opensaas/prisma-client"
-}
-
-datasource db {
-  provider = "mysql"
-}
-"
-`;
-
-exports[`Generate Command Integration > Generator Integration > should handle different database providers > postgresql-provider 1`] = `
-"generator client {
-  provider = "prisma-client"
-  output   = "../.opensaas/prisma-client"
-}
-
-datasource db {
-  provider = "postgresql"
-}
-"
-`;
-
-exports[`Generate Command Integration > Generator Integration > should handle different database providers > sqlite-provider 1`] = `
-"generator client {
-  provider = "prisma-client"
-  output   = "../.opensaas/prisma-client"
-}
-
-datasource db {
-  provider = "sqlite"
-}
-"
-`;
-
-exports[`Generate Command Integration > Generator Integration > should handle empty lists config > empty-lists-schema 1`] = `
-"generator client {
-  provider = "prisma-client"
-  output   = "../.opensaas/prisma-client"
-}
-
-datasource db {
-  provider = "sqlite"
-}
-"
-`;
-
-exports[`Generate Command Integration > Generator Integration > should handle empty lists config > empty-lists-types 1`] = `
-"/**
- * Generated types from OpenSaas configuration
- * DO NOT EDIT - This file is automatically generated
- */
-
-import type { Session as OpensaasSession, StorageUtils, ServerActionProps, AccessControlledDB, AccessContext } from '@opensaas/stack-core'
-import type { PrismaClient, Prisma } from './prisma-client/client'
-import type { PluginServices } from './plugin-types'
-
-/**
- * Custom DB type that uses Prisma's conditional types with virtual and transformed field support
- * Types change based on select/include - relationships only present when explicitly included
- * Virtual fields and transformed fields are added to the base model type
- */
-export type CustomDB = Omit<AccessControlledDB<PrismaClient>, 
-  
-> & {
-}
-
-/**
- * Context type compatible with AccessContext but with CustomDB for virtual field typing
- * Extends AccessContext and overrides db property to include virtual fields in output types
- */
-export type Context<TSession extends OpensaasSession = OpensaasSession> = Omit<AccessContext<PrismaClient>, 'db' | 'session'> & {
-  db: CustomDB
-  session: TSession
-  serverAction: (props: ServerActionProps) => Promise<unknown>
-  sudo: () => Context<TSession>
-}"
-`;
-
-exports[`Generate Command Integration > Generator Integration > should overwrite existing files > overwrite-after 1`] = `
-"generator client {
-  provider = "prisma-client"
-  output   = "../.opensaas/prisma-client"
-}
-
-datasource db {
-  provider = "sqlite"
-}
-
-model Post {
-  id        String   @id @default(cuid())
-  title        String?
-  createdAt DateTime @default(now())
-  updatedAt DateTime @updatedAt
-}
-"
-`;
-
-exports[`Generate Command Integration > Generator Integration > should overwrite existing files > overwrite-before 1`] = `
-"generator client {
-  provider = "prisma-client"
-  output   = "../.opensaas/prisma-client"
-}
-
-datasource db {
-  provider = "sqlite"
-}
-
-model User {
-  id        String   @id @default(cuid())
-  name         String?
-  createdAt DateTime @default(now())
-  updatedAt DateTime @updatedAt
-}
-"
-`;