@opensaas/stack-cli 0.4.0 → 0.6.0

package/plugin/commands/validate-migration.md

@@ -0,0 +1,34 @@
+---
+description: Validate the generated opensaas.config.ts file
+---
+
+Validate the generated opensaas.config.ts file.
+
+## Instructions
+
+1. Check if opensaas.config.ts exists in the project root
+
+2. If it exists, verify:
+   - Syntax is valid TypeScript
+   - All imports are correct
+   - Database config is complete
+   - Lists match original schema
+
+3. Try running:
+
+   ```bash
+   npx @opensaas/stack-cli generate
+   ```
+
+4. Report any errors and suggest fixes
+
+5. If validation passes, confirm next steps:
+   - `npx prisma generate`
+   - `npx prisma db push`
+   - `pnpm dev`
+
+## Common Issues
+
+- Missing dependencies → suggest `pnpm add ...`
+- Database URL not set → remind about .env file
+- Type errors → suggest specific fixes

package/plugin/skills/opensaas-migration/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: opensaas-migration
+description: Expert knowledge for migrating projects to OpenSaaS Stack. Use when discussing migration strategies, access control patterns, or OpenSaaS Stack configuration best practices.
+---
+
+# OpenSaaS Stack Migration
+
+Expert guidance for migrating existing projects to OpenSaaS Stack.
+
+## When to Use This Skill
+
+Use this skill when:
+
+- Planning a migration from Prisma, KeystoneJS, or Next.js
+- Designing access control patterns
+- Configuring `opensaas.config.ts`
+- Troubleshooting migration issues
+- Explaining OpenSaaS Stack concepts
+
+## Migration Process
+
+### 1. Schema Analysis
+
+**Prisma Projects:**
+
+- Analyze existing `schema.prisma`
+- Identify models, fields, and relationships
+- Note any Prisma-specific features used
+
+**KeystoneJS Projects:**
+
+- Review list definitions
+- Map KeystoneJS fields to OpenSaaS fields
+- Identify access control patterns
+
+### 2. Access Control Design
+
+**Common Patterns:**
+
+```typescript
+// Public read, authenticated write
+operation: {
+  query: () => true,
+  create: ({ session }) => !!session?.userId,
+  update: ({ session }) => !!session?.userId,
+  delete: ({ session }) => !!session?.userId,
+}
+
+// Author-only access
+operation: {
+  query: () => true,
+  update: ({ session, item }) => item.authorId === session?.userId,
+  delete: ({ session, item }) => item.authorId === session?.userId,
+}
+
+// Admin-only
+operation: {
+  query: ({ session }) => session?.role === 'admin',
+  create: ({ session }) => session?.role === 'admin',
+  update: ({ session }) => session?.role === 'admin',
+  delete: ({ session }) => session?.role === 'admin',
+}
+
+// Filter-based access
+operation: {
+  query: ({ session }) => ({
+    where: { authorId: { equals: session?.userId } }
+  }),
+}
+```
+
+### 3. Field Mapping
+
+**Prisma to OpenSaaS:**
+
+| Prisma Type | OpenSaaS Field                 |
+| ----------- | ------------------------------ |
+| `String`    | `text()`                       |
+| `Int`       | `integer()`                    |
+| `Boolean`   | `checkbox()`                   |
+| `DateTime`  | `timestamp()`                  |
+| `Enum`      | `select({ options: [...] })`   |
+| `Relation`  | `relationship({ ref: '...' })` |
+
+**KeystoneJS to OpenSaaS:**
+
+| KeystoneJS Field | OpenSaaS Field   |
+| ---------------- | ---------------- |
+| `text`           | `text()`         |
+| `integer`        | `integer()`      |
+| `checkbox`       | `checkbox()`     |
+| `timestamp`      | `timestamp()`    |
+| `select`         | `select()`       |
+| `relationship`   | `relationship()` |
+| `password`       | `password()`     |
+
+### 4. Database Configuration
+
+**SQLite (Development):**
+
+```typescript
+import { PrismaBetterSQLite3 } from '@prisma/adapter-better-sqlite3'
+import Database from 'better-sqlite3'
+
+export default 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 })
+    },
+  },
+})
+```
+
+**PostgreSQL (Production):**
+
+```typescript
+import { PrismaPg } from '@prisma/adapter-pg'
+import pg from 'pg'
+
+export default 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 })
+    },
+  },
+})
+```
+
+## Common Migration Challenges
+
+### Challenge: Preserving Existing Data
+
+**Solution:**
+
+- Use `opensaas generate` to create Prisma schema
+- Use `prisma db push` instead of migrations for existing databases
+- Never use `prisma migrate dev` with existing data
+
+### Challenge: Complex Access Control
+
+**Solution:**
+
+- Start with simple boolean access control
+- Iterate to filter-based access as needed
+- Use field-level access for sensitive data
+
+### Challenge: Custom Field Types
+
+**Solution:**
+
+- Create custom field builders extending `BaseFieldConfig`
+- Implement `getZodSchema`, `getPrismaType`, `getTypeScriptType`
+- Register UI components for admin interface
+
+## Migration Checklist
+
+- [ ] Analyze existing schema
+- [ ] Design access control patterns
+- [ ] Create `opensaas.config.ts`
+- [ ] Configure database adapter
+- [ ] Run `opensaas generate`
+- [ ] Run `prisma generate`
+- [ ] Run `prisma db push`
+- [ ] Test access control
+- [ ] Verify admin UI
+- [ ] Update application code to use context
+- [ ] Test all CRUD operations
+- [ ] Deploy to production
+
+## Best Practices
+
+1. **Start Simple**: Begin with basic access control, refine later
+2. **Test Access Control**: Verify permissions work as expected
+3. **Use Context Everywhere**: Replace direct Prisma calls with `context.db`
+4. **Leverage Plugins**: Use `@opensaas/stack-auth` for authentication
+5. **Version Control**: Commit `opensaas.config.ts` to git
+6. **Document Decisions**: Comment complex access control logic
+
+## Resources
+
+- [OpenSaaS Stack Documentation](https://stack.opensaas.au/)
+- [Migration Guide](https://stack.opensaas.au/guides/migration)
+- [Access Control Guide](https://stack.opensaas.au/core-concepts/access-control)
+- [Field Types](https://stack.opensaas.au/core-concepts/field-types)

package/.turbo/turbo-build.log

@@ -1,4 +0,0 @@
-
-> @opensaas/stack-cli@0.4.0 build /home/runner/work/stack/stack/packages/cli
-> tsc
-

package/CHANGELOG.md

@@ -1,410 +0,0 @@
-# @opensaas/stack-cli
-
-## 0.4.0
-
-### Minor Changes
-
-- [#170](https://github.com/OpenSaasAU/stack/pull/170) [`3c4db9d`](https://github.com/OpenSaasAU/stack/commit/3c4db9d8318fc73d291991d8bdfa4f607c3a50ea) Thanks [@list({](https://github.com/list({)! - Add support for virtual fields with proper TypeScript type generation
-
-  Virtual fields are computed fields that don't exist in the database but are added to query results at runtime. This feature enables derived or computed values to be included in your API responses with full type safety.
-
-  **New Features:**
-  - Added `virtual()` field type for defining computed fields in your schema
-  - Virtual fields are automatically excluded from database schema and input types
-  - Virtual fields appear in output types with full TypeScript autocomplete
-  - Virtual fields support `resolveOutput` hooks for custom computation logic
-
-  **Type System Improvements:**
-  - Generated Context type now properly extends AccessContext from core
-  - Separate Input and Output types (e.g., `UserOutput` includes virtual fields, `UserCreateInput` does not)
-  - UI components now accept `AccessContext<any>` for better compatibility with custom context types
-  - Type aliases provide convenience (e.g., `User = UserOutput`)
-
-  **Example Usage:**
-
-  ```typescript
-  import { list, text, virtual } from '@opensaas/stack-core'
-
-  export default config({
-    lists: {
-
-        fields: {
-          name: text(),
-          email: text(),
-          displayName: virtual({
-            type: 'string',
-            hooks: {
-              resolveOutput: async ({ item }) => {
-                return `${item.name} (${item.email})`
-              },
-            },
-          }),
-        },
-      }),
-    },
-  })
-  ```
-
-  The `displayName` field will automatically appear in query results with full TypeScript support, but won't be part of create/update operations or the database schema.
-
-### Patch Changes
-
-- [#154](https://github.com/OpenSaasAU/stack/pull/154) [`edf1e5f`](https://github.com/OpenSaasAU/stack/commit/edf1e5fa4cfefcb7bc09bf45d4702260e6d0d3aa) Thanks [@renovate](https://github.com/apps/renovate)! - Update dependency chokidar to v5
-
-- [#172](https://github.com/OpenSaasAU/stack/pull/172) [`929a2a9`](https://github.com/OpenSaasAU/stack/commit/929a2a9a2dfa80b1d973d259dd87828d644ea58d) Thanks [@list<Lists.User.TypeInfo>({](https://github.com/list<Lists.User.TypeInfo>({), [@list<Lists.User.TypeInfo>({](https://github.com/list<Lists.User.TypeInfo>({)! - Improve TypeScript type inference for field configs and list-level hooks by automatically passing TypeInfo from list level down
-
-  This change eliminates the need to manually specify type parameters on field builders when using features like virtual fields, and fixes a critical bug where list-level hooks weren't receiving properly typed parameters.
-
-  ## Field Type Inference Improvements
-
-  Previously, users had to write `virtual<Lists.User.TypeInfo>({...})` to get proper type inference. Now TypeScript automatically infers the correct types from the list-level type parameter.
-
-  **Example:**
-
-  ```typescript
-  // Before
-
-    fields: {
-      displayName: virtual<Lists.User.TypeInfo>({
-        type: 'string',
-        hooks: {
-          resolveOutput: ({ item }) => `${item.name} (${item.email})`,
-        },
-      }),
-    },
-  })
-
-  // After
-
-    fields: {
-      displayName: virtual({
-        type: 'string',
-        hooks: {
-          resolveOutput: ({ item }) => `${item.name} (${item.email})`,
-        },
-      }),
-    },
-  })
-  ```
-
-  ## List-Level Hooks Type Inference Fix
-
-  Fixed a critical type parameter mismatch where `Hooks<TTypeInfo>` was passing the entire TypeInfo object as the first parameter instead of properly destructuring it into three required parameters:
-  1. `TOutput` - The item type (what's stored in DB)
-  2. `TCreateInput` - Prisma create input type
-  3. `TUpdateInput` - Prisma update input type
-
-  **Impact:**
-  - `resolveInput` now receives proper Prisma input types (e.g., `PostCreateInput`, `PostUpdateInput`)
-  - `validateInput` has access to properly typed input data
-  - `beforeOperation` and `afterOperation` have correct item types
-  - All list-level hook callbacks now get full IntelliSense and type checking
-
-  **Example:**
-
-  ```typescript
-  Post: list<Lists.Post.TypeInfo>({
-    fields: { title: text(), content: text() },
-    hooks: {
-      resolveInput: async ({ operation, resolvedData }) => {
-        // ✅ resolvedData is now properly typed as PostCreateInput or PostUpdateInput
-        // ✅ Full autocomplete for title, content, etc.
-        if (operation === 'create') {
-          console.log(resolvedData.title) // TypeScript knows this is string | undefined
-        }
-        return resolvedData
-      },
-      beforeOperation: async ({ operation, item }) => {
-        // ✅ item is now properly typed as Post with all fields
-        if (operation === 'update' && item) {
-          console.log(item.title) // TypeScript knows this is string
-          console.log(item.createdAt) // TypeScript knows this is Date
-        }
-      },
-    },
-  })
-  ```
-
-  ## Breaking Changes
-  - Field types now accept full `TTypeInfo extends TypeInfo` instead of just `TItem`
-  - `FieldsWithItemType` utility replaced with `FieldsWithTypeInfo`
-  - All field builders updated to use new type signature
-  - List-level hooks now receive properly typed parameters (may reveal existing type errors)
-
-  ## Benefits
-  - ✨ Cleaner code without manual type parameter repetition
-  - 🎯 Better type inference in both field-level and list-level hooks
-  - 🔄 Consistent type flow from list configuration down to individual fields
-  - 🛡️ Maintained full type safety with improved DX
-  - 💡 Full IntelliSense support in all hook callbacks
-
-- Updated dependencies [[`527b677`](https://github.com/OpenSaasAU/stack/commit/527b677ab598070185e23d163a9e99bc20f03c49), [`929a2a9`](https://github.com/OpenSaasAU/stack/commit/929a2a9a2dfa80b1d973d259dd87828d644ea58d), [`3c4db9d`](https://github.com/OpenSaasAU/stack/commit/3c4db9d8318fc73d291991d8bdfa4f607c3a50ea)]:
-  - @opensaas/stack-core@0.4.0
-
-## 0.3.0
-
-### Patch Changes
-
-- Updated dependencies []:
-  - @opensaas/stack-core@0.3.0
-
-## 0.2.0
-
-### Minor Changes
-
-- [#107](https://github.com/OpenSaasAU/stack/pull/107) [`f4f3966`](https://github.com/OpenSaasAU/stack/commit/f4f3966faedba07d2cf412fab826d81e30c63a6c) Thanks [@borisno2](https://github.com/borisno2)! - # Add MCP Server for AI-Assisted Development
-
-  ## New Features
-
-  ### CLI Package (@opensaas/stack-cli)
-  - **New `opensaas mcp` command group** for AI-assisted development:
-    - `opensaas mcp install` - Install MCP server in Claude Code
-    - `opensaas mcp uninstall` - Remove MCP server from Claude Code
-    - `opensaas mcp start` - Start MCP server directly (for debugging)
-  - **Feature-driven development tools**:
-    - Interactive feature implementation wizards (authentication, blog, comments, file-upload, semantic-search)
-    - Live documentation search from stack.opensaas.au
-    - Code generation following OpenSaaS best practices
-    - Smart feature suggestions based on your current app
-    - Config validation
-  - **MCP tools available in Claude Code**:
-    - `opensaas_implement_feature` - Start feature wizard
-    - `opensaas_feature_docs` - Search documentation
-    - `opensaas_list_features` - Browse available features
-    - `opensaas_suggest_features` - Get personalized recommendations
-    - `opensaas_validate_feature` - Validate implementations
-
-  ### create-opensaas-app
-  - **Interactive MCP setup prompt** during project creation
-  - Option to enable AI development tools automatically
-  - Automatic installation of MCP server if user opts in
-  - Helpful instructions if MCP installation is declined or fails
-
-  ## Installation
-
-  Enable AI development tools for an existing project:
-
-  ```bash
-  npx @opensaas/stack-cli mcp install
-  ```
-
-  Or during project creation:
-
-  ```bash
-  npm create opensaas-app@latest my-app
-  # When prompted: Enable AI development tools? → yes
-  ```
-
-  ## Benefits
-  - **Build apps faster**: Describe what you want to build, get complete implementations
-  - **Feature-driven development**: Work with high-level features instead of low-level config
-  - **Best practices baked in**: Generated code follows OpenSaaS Stack patterns
-  - **Live documentation**: Always up-to-date docs from the official site
-  - **Single toolkit**: All developer commands in one CLI
-
-  ## Example Usage
-
-  With Claude Code installed and the MCP server enabled, you can:
-
-  ```
-  You: "I want to build a food tracking app"
-
-  Claude Code uses MCP tools to:
-  1. Ask clarifying questions about requirements
-  2. Implement authentication feature (wizard)
-  3. Create custom Food and FoodLog lists
-  4. Generate complete code with UI and access control
-  5. Provide testing and deployment guidance
-  ```
-
-- [#132](https://github.com/OpenSaasAU/stack/pull/132) [`fcf5cb8`](https://github.com/OpenSaasAU/stack/commit/fcf5cb8bbd55d802350b8d97e342dd7f6368163b) Thanks [@borisno2](https://github.com/borisno2)! - Upgrade to Prisma 7 with database adapter support
-
-  ## Breaking Changes
-
-  ### Required `prismaClientConstructor`
-
-  Prisma 7 requires database adapters. All configs must now include `prismaClientConstructor`:
-
-  ```typescript
-  import { PrismaBetterSQLite3 } from '@prisma/adapter-better-sqlite3'
-  import Database from 'better-sqlite3'
-
-  export default config({
-    db: {
-      provider: 'sqlite',
-      prismaClientConstructor: (PrismaClient) => {
-        const db = new Database(process.env.DATABASE_URL || './dev.db')
-        const adapter = new PrismaBetterSQLite3(db)
-        return new PrismaClient({ adapter })
-      },
-    },
-  })
-  ```
-
-  ### Removed `url` from `DatabaseConfig`
-
-  The `url` field has been removed from the `DatabaseConfig` type. Database connection URLs are now passed directly to adapters in `prismaClientConstructor`:
-
-  ```typescript
-  // ❌ Before (Prisma 6)
-  db: {
-    provider: 'sqlite',
-    url: 'file:./dev.db',  // url in config
-  }
-
-  // ✅ After (Prisma 7)
-  db: {
-    provider: 'sqlite',
-    prismaClientConstructor: (PrismaClient) => {
-      const adapter = new PrismaBetterSQLite3({ url: './dev.db' })  // url in adapter
-      return new PrismaClient({ adapter })
-    },
-  }
-  ```
-
-  ### Generated Schema Changes
-  - Generator provider changed from `prisma-client-js` to `prisma-client`
-  - Removed `url` field from datasource block
-  - Database URL now passed via adapter in `prismaClientConstructor`
-
-  ### Required Dependencies
-
-  Install the appropriate adapter for your database:
-  - **SQLite**: `@prisma/adapter-better-sqlite3` + `better-sqlite3`
-  - **PostgreSQL**: `@prisma/adapter-pg` + `pg`
-  - **MySQL**: `@prisma/adapter-mysql` + `mysql2`
-
-  ## Migration Steps
-  1. Install Prisma 7 and adapter:
-
-     ```bash
-     pnpm add @prisma/client@7 @prisma/adapter-better-sqlite3 better-sqlite3
-     pnpm add -D prisma@7
-     ```
-
-  2. Update your `opensaas.config.ts` to include `prismaClientConstructor` (see example above)
-  3. Regenerate schema and client:
-
-     ```bash
-     pnpm generate
-     npx prisma generate
-     ```
-
-  4. Push schema to database:
-     ```bash
-     pnpm db:push
-     ```
-
-  See the updated documentation in CLAUDE.md for more examples including PostgreSQL and custom adapters.
-
-### Patch Changes
-
-- [#107](https://github.com/OpenSaasAU/stack/pull/107) [`f4f3966`](https://github.com/OpenSaasAU/stack/commit/f4f3966faedba07d2cf412fab826d81e30c63a6c) Thanks [@borisno2](https://github.com/borisno2)! - Add strict typing for plugin runtime services
-
-  This change implements fully typed plugin runtime services, providing autocomplete and type safety for `context.plugins` throughout the codebase.
-
-  **Core Changes:**
-  - Extended `Plugin` type with optional `runtimeServiceTypes` metadata for type-safe code generation
-  - Converted `OpenSaasConfig` and `AccessContext` from `type` to `interface` to enable module augmentation
-  - Plugins can now declare their runtime service type information
-
-  **Auth Plugin:**
-  - Added `AuthRuntimeServices` interface defining runtime service types
-  - Exported runtime types from package
-  - Users now get full autocomplete for `context.plugins.auth.getUser()` and `context.plugins.auth.getCurrentUser()`
-
-  **RAG Plugin:**
-  - Added `RAGRuntimeServices` interface defining runtime service types
-  - Exported runtime types from package
-  - Users now get full autocomplete for `context.plugins.rag.generateEmbedding()` and `context.plugins.rag.generateEmbeddings()`
-
-  **CLI Generator:**
-  - Enhanced plugin types generator to import and use plugin runtime service types
-  - Generated `.opensaas/plugin-types.ts` now includes proper type imports
-  - `PluginServices` interface extends `Record<string, Record<string, any> | undefined>` for type compatibility
-  - Maintains backwards compatibility with plugins that don't provide type metadata
-
-  **UI Package:**
-  - Updated `AdminUI` props to accept contexts with typed plugin services
-  - Ensures compatibility between generated context types and UI components
-
-  **Benefits:**
-  - Full TypeScript autocomplete for all plugin runtime methods
-  - Compile-time type checking catches errors early
-  - Better IDE experience with hover documentation and jump-to-definition
-  - Backwards compatible - third-party plugins without type metadata continue to work
-  - Zero type errors in examples
-
-  **Example:**
-
-  ```typescript
-  const context = await getContext()
-
-  // Fully typed with autocomplete
-  context.plugins.auth.getUser('123') // (userId: string) => Promise<unknown>
-  context.plugins.rag.generateEmbedding('text') // (text: string, providerName?: string) => Promise<number[]>
-  ```
-
-- Updated dependencies [[`fcf5cb8`](https://github.com/OpenSaasAU/stack/commit/fcf5cb8bbd55d802350b8d97e342dd7f6368163b), [`3851a3c`](https://github.com/OpenSaasAU/stack/commit/3851a3cf72e78dc6f01a73c6fff97deca6fad043), [`f4f3966`](https://github.com/OpenSaasAU/stack/commit/f4f3966faedba07d2cf412fab826d81e30c63a6c)]:
-  - @opensaas/stack-core@0.2.0
-
-## 0.1.7
-
-### Patch Changes
-
-- 372d467: Add sudo to context to bypass access control
-- Updated dependencies [372d467]
-  - @opensaas/stack-core@0.1.7
-
-## 0.1.6
-
-### Patch Changes
-
-- 39996ca: Fix missing StoredEmbedding type import in generated types. Fields can now declare TypeScript imports needed for their types via the new `getTypeScriptImports()` method. This resolves the type error where `StoredEmbedding` was referenced but not imported in the generated `.opensaas/types.ts` file.
-- 39996ca: Add plugin mechanism
-- Updated dependencies [39996ca]
-- Updated dependencies [39996ca]
-  - @opensaas/stack-core@0.1.6
-
-## 0.1.5
-
-### Patch Changes
-
-- 17eaafb: Update package urls
-- Updated dependencies [17eaafb]
-  - @opensaas/stack-core@0.1.5
-
-## 0.1.4
-
-### Patch Changes
-
-- d2d1720: clean up dependency
-- Updated dependencies [d013859]
-  - @opensaas/stack-core@0.1.4
-
-## 0.1.3
-
-### Patch Changes
-
-- @opensaas/stack-core@0.1.3
-- @opensaas/stack-mcp@0.1.3
-
-## 0.1.2
-
-### Patch Changes
-
-- 7bb96e6: Fix up init command to work
-  - @opensaas/stack-core@0.1.2
-  - @opensaas/stack-mcp@0.1.2
-
-## 0.1.1
-
-### Patch Changes
-
-- f8ebc0e: Add base mcp server
-- 045c071: Add field and image upload
-- Updated dependencies [9a3fda5]
-- Updated dependencies [f8ebc0e]
-- Updated dependencies [045c071]
-  - @opensaas/stack-core@0.1.1
-  - @opensaas/stack-mcp@0.1.1