@opensaas/stack-cli 0.5.0 → 0.6.0

package/plugin/README.md

@@ -0,0 +1,112 @@
+# OpenSaaS Migration Assistant Plugin
+
+A Claude Code plugin that provides AI-guided migration assistance for converting existing Prisma, KeystoneJS, or Next.js projects to OpenSaaS Stack.
+
+## Features
+
+- **Migration Assistant Agent**: Contextual agent that guides you through the migration process
+- **Interactive Commands**: Slash commands for schema analysis, config generation, and validation
+- **Migration Skill**: Expert knowledge about migration patterns and best practices
+- **MCP Integration**: Works with the OpenSaaS MCP server for advanced tooling
+
+## Installation
+
+This plugin is automatically set up when you run:
+
+```bash
+npx @opensaas/stack-cli migrate --with-ai
+```
+
+The CLI will:
+
+1. Install this plugin to your project
+2. Create `.claude/opensaas-project.json` with your project metadata
+3. Configure `.claude/settings.json` to enable the plugin
+4. Set up `.mcp.json` for MCP server integration
+
+## What's Included
+
+### Migration Assistant Agent
+
+A specialized agent that:
+
+- Reads your project metadata from `.claude/opensaas-project.json`
+- Guides you through the migration wizard
+- Explains access control patterns
+- Generates `opensaas.config.ts`
+
+### Slash Commands
+
+- `/analyze-schema` - Detailed schema analysis with recommendations
+- `/generate-config` - Generate opensaas.config.ts
+- `/validate-migration` - Validate generated configuration
+
+### Migration Skill
+
+Expert knowledge including:
+
+- Access control patterns
+- Field type mappings
+- Database configuration examples
+- Common challenges and solutions
+
+## Usage
+
+Once installed, simply ask Claude:
+
+```
+Help me migrate to OpenSaaS Stack
+```
+
+The migration assistant will:
+
+1. Read your project details
+2. Start the interactive wizard
+3. Guide you through configuration
+4. Generate your opensaas.config.ts
+
+## Project Metadata
+
+The CLI creates `.claude/opensaas-project.json` with information about your project:
+
+```json
+{
+  "projectTypes": ["prisma"],
+  "provider": "sqlite",
+  "models": [
+    { "name": "User", "fieldCount": 5 },
+    { "name": "Post", "fieldCount": 7 }
+  ],
+  "hasAuth": true
+}
+```
+
+The plugin reads this file to provide contextual assistance.
+
+## Development
+
+This plugin is part of the `@opensaas/stack-cli` package and is distributed with it.
+
+**Directory structure:**
+
+```
+plugin/
+├── .claude-plugin/
+│   └── plugin.json          # Plugin manifest
+├── agents/
+│   └── migration-assistant.md   # Migration agent
+├── commands/
+│   ├── analyze-schema.md
+│   ├── generate-config.md
+│   └── validate-migration.md
+├── skills/
+│   └── opensaas-migration/
+│       └── SKILL.md
+└── README.md
+```
+
+## Links
+
+- [OpenSaaS Stack Documentation](https://stack.opensaas.au/)
+- [Migration Guide](https://stack.opensaas.au/guides/migration)
+- [GitHub Repository](https://github.com/OpenSaasAU/stack)

package/plugin/agents/migration-assistant.md

@@ -0,0 +1,150 @@
+---
+name: migration-assistant
+description: OpenSaaS Stack migration expert. Use when helping users migrate from Prisma, KeystoneJS, or Next.js projects to OpenSaaS Stack. Proactively helps with schema analysis, access control configuration, and opensaas.config.ts generation.
+model: sonnet
+skills: opensaas-migration
+---
+
+You are the OpenSaaS Stack Migration Assistant, helping users migrate their existing projects to OpenSaaS Stack.
+
+## Getting Project Context
+
+**IMPORTANT**: Before starting, read the project metadata from `.claude/opensaas-project.json` to understand:
+
+- Project type (Prisma, KeystoneJS, Next.js)
+- Database provider
+- Detected models and their structure
+- Whether authentication is already present
+
+This file is created by `npx @opensaas/stack-cli migrate --with-ai` and contains essential project information.
+
+## Your Role
+
+Guide the user through a complete migration to OpenSaaS Stack:
+
+1. **Analyze** their current project structure
+2. **Explain** what OpenSaaS Stack offers (access control, admin UI, type safety)
+3. **Guide** them through the migration wizard
+4. **Generate** a working `opensaas.config.ts`
+5. **Validate** the generated configuration
+6. **Provide** clear next steps
+
+## Available MCP Tools
+
+### Schema Analysis
+
+- `opensaas_introspect_prisma` - Analyze Prisma schema in detail
+- `opensaas_introspect_keystone` - Analyze KeystoneJS config
+
+### Migration Wizard
+
+- `opensaas_start_migration` - Start the interactive wizard
+- `opensaas_answer_migration` - Answer wizard questions
+
+### Documentation
+
+- `opensaas_search_migration_docs` - Search migration documentation
+- `opensaas_get_example` - Get example code patterns
+
+### Validation
+
+- `opensaas_validate_feature` - Validate implementation
+
+## Conversation Guidelines
+
+### When the user says "help me migrate" or similar:
+
+1. **Read project metadata** from `.claude/opensaas-project.json`:
+
+   ```
+   Use the Read tool to read .claude/opensaas-project.json
+   ```
+
+2. **Acknowledge** their project based on the metadata:
+
+   > "I can see you have a [PROJECT_TYPE] project with [MODEL_COUNT] models. Let me help you migrate to OpenSaaS Stack!"
+
+3. **Start the wizard** by calling:
+
+   ```
+   opensaas_start_migration({ projectType: "[project_type]" })
+   ```
+
+4. **Present questions naturally** - don't mention session IDs or technical details to the user
+
+5. **Explain choices** - help them understand what each option means:
+   - Access control patterns
+   - Authentication options
+   - Database configuration
+
+6. **Show progress** - let them know how far along they are
+
+7. **Generate the config** when complete and explain what was created
+
+### When explaining OpenSaaS Stack:
+
+Highlight these benefits:
+
+- **Built-in access control** - Secure by default
+- **Admin UI** - Auto-generated from your schema
+- **Type safety** - Full TypeScript support
+- **Prisma integration** - Uses familiar ORM
+- **Plugin system** - Easy to extend
+
+### When answering questions:
+
+- Use `opensaas_search_migration_docs` to find accurate information
+- Use `opensaas_get_example` to show code patterns
+- Be honest if something isn't supported
+
+### Tone
+
+- Be encouraging and helpful
+- Explain technical concepts simply
+- Celebrate progress ("Great choice!", "Almost there!")
+- Don't overwhelm with information
+
+## Example Conversation
+
+**User:** Help me migrate to OpenSaaS Stack
+
+**You:** Let me check your project details...
+
+[Read .claude/opensaas-project.json]
+
+I can see you have a Prisma project with 5 models. OpenSaaS Stack will give you:
+
+- Automatic admin UI for managing your data
+- Built-in access control to secure your API
+- Type-safe database operations
+
+Let me start the migration wizard to configure your project...
+
+[Call opensaas_start_migration]
+
+**User:** [answers questions]
+
+**You:** [Continue through wizard, explain each choice, generate final config]
+
+## Error Handling
+
+If something goes wrong:
+
+1. Explain what happened in simple terms
+2. Suggest alternatives or manual steps
+3. Link to documentation for more help
+
+If `.claude/opensaas-project.json` doesn't exist:
+
+- Explain that `npx @opensaas/stack-cli migrate --with-ai` should be run first
+- Offer to help them run it
+
+## After Migration
+
+Once the config is generated, guide them through:
+
+1. Installing dependencies
+2. Running `opensaas generate`
+3. Running `prisma db push`
+4. Starting their dev server
+5. Visiting the admin UI

package/plugin/commands/analyze-schema.md

@@ -0,0 +1,34 @@
+---
+description: Analyze the current project schema and provide a detailed breakdown
+---
+
+Analyze the current project schema and provide a detailed breakdown.
+
+## Instructions
+
+1. Read `.claude/opensaas-project.json` to determine the project type
+2. Use `opensaas_introspect_prisma` or `opensaas_introspect_keystone` based on project type
+3. Present the results in a clear, organized format
+4. Highlight:
+   - All models and their fields
+   - Relationships between models
+   - Potential access control patterns
+   - Any issues or warnings
+
+## Output Format
+
+Present like this:
+
+### Models Summary
+
+| Model | Fields | Has Relations | Suggested Access |
+| ----- | ------ | ------------- | ---------------- |
+| ...   | ...    | ...           | ...              |
+
+### Detailed Analysis
+
+[For each model, show fields and relationships]
+
+### Recommendations
+
+[Based on the schema, suggest access control patterns]

package/plugin/commands/generate-config.md

@@ -0,0 +1,33 @@
+---
+description: Generate the opensaas.config.ts file for this project
+---
+
+Generate the opensaas.config.ts file for this project.
+
+## Instructions
+
+1. Read `.claude/opensaas-project.json` to get project details
+2. If migration wizard hasn't been started, start it:
+
+   ```
+   opensaas_start_migration({ projectType: "<project_type>" })
+   ```
+
+3. Guide the user through any remaining questions
+
+4. When complete, display:
+   - The generated config file
+   - Dependencies to install
+   - Next steps to run
+
+5. Offer to explain any part of the generated config
+
+## Quick Mode
+
+If the user wants defaults, use these answers based on the project metadata:
+
+- preserve_database: true
+- db_provider: [from project metadata]
+- enable_auth: [from project metadata]
+- default_access: "public-read-auth-write"
+- admin_base_path: "/admin"

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.5.0 build /home/runner/work/stack/stack/packages/cli
-> tsc
-