create-lego-one 2.0.12 → 2.0.14

package/template/PROMPT.md

@@ -0,0 +1,457 @@
+# PROMPT.md
+
+**Lego-One Vibe Coding Session Template**
+
+> Use this template to provide complete context for AI-assisted development sessions. Fill out all sections before starting.
+
+---
+
+## Session Information
+
+**Date:** `{YYYY-MM-DD}`
+**Session ID:** `{optional: for tracking related work}`
+**Related Checkpoint:** `{optional: link to /docs/checkpoints/ file}`
+
+---
+
+## Task Description
+
+**What needs to be done?**
+
+<!-- Provide a detailed explanation of the feature, bugfix, or enhancement -->
+
+
+**Success Criteria:**
+
+<!-- Define what "done" looks like. What should work? What should be tested? -->
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] Criterion 3
+
+---
+
+## Target Scope
+
+**Is this for:**
+
+- [ ] **Host/Framework (Kernel)** - Core system changes (auth, RBAC, shared state, etc.)
+- [ ] **Application Plugin** - New or modified plugin for this application
+
+**Clarification:**
+
+<!-- If Framework: Explain why core changes are needed -->
+<!-- If Application: Describe which plugin or what new plugin to create -->
+
+---
+
+## Type & Classification
+
+**What type of work is this?**
+
+- [ ] **New Plugin** - Creating a brand new plugin
+- [ ] **Plugin Enhancement** - Adding features to existing plugin
+- [ ] **Bug Fix** - Fixing an issue
+- [ ] **Refactoring** - Code improvement without behavior change
+- [ ] **Documentation** - Updating docs or creating new docs
+
+**Plugin Name (if applicable):**
+
+<!-- e.g., @lego/plugin-calculator, @lego/plugin-inventory, etc. -->
+
+---
+
+## Dependencies
+
+**Required Services:**
+
+- [ ] PocketBase (database)
+- [ ] Authentication (user login required)
+- [ ] Authorization (RBAC/permissions)
+- [ ] Organization context (multi-tenancy)
+- [ ] External API (specify which)
+
+**Database Collections (if new data needed):**
+
+<!-- List PocketBase collections that need to be created -->
+
+| Collection Name | Purpose | Multi-Tenancy Required? |
+|----------------|---------|------------------------|
+| `example_items` | Stores example data | Yes (organizationId, ownerId) |
+
+**npm Packages (if needed):**
+
+<!-- List any additional dependencies -->
+
+```bash
+pnpm add <package-name>
+```
+
+---
+
+## UI/UX Requirements
+
+**Pages/Routes:**
+
+<!-- Does this plugin need dedicated pages? List them here -->
+
+| Route Path | Page Name | Protected? | Required Permissions |
+|------------|-----------|-----------|---------------------|
+| `/my-plugin` | MyPluginPage | Yes | `myplugin.read` |
+| `/my-plugin/:id` | ItemDetailPage | Yes | `myplugin.read` |
+
+**Slot Injections:**
+
+<!-- Should this plugin inject UI into existing slots? -->
+
+| Slot Location | Component | Purpose | Order |
+|---------------|-----------|---------|-------|
+| `sidebar:nav` | NavigationLink | Add to sidebar navigation | 100 |
+
+**UI Components Needed:**
+
+<!-- List UI components required (use existing from kernel when possible) -->
+
+- [ ] Forms (use existing: Button, Input, Select, etc.)
+- [ ] Tables/Lists
+- [ ] Dialogs/Modals
+- [ ] Toasts/Notifications
+- [ ] Custom components (describe)
+
+**Wireframe/Mockup (Optional):**
+
+<!-- Link to design or describe layout -->
+
+```
+┌─────────────────────────────────────┐
+│ Page Header                          │
+│ [Button] [Filter] [Search]           │
+├─────────────────────────────────────┤
+│ Table/List View                      │
+│ - Item 1                             │
+│ - Item 2                             │
+└─────────────────────────────────────┘
+```
+
+---
+
+## Logic Flow
+
+**How should the feature work?**
+
+<!-- Step-by-step description of the feature behavior -->
+
+1. **User Action:** User clicks "Create Item" button
+2. **System Response:** Opens dialog with form
+3. **Validation:** Form validates using Zod schema
+4. **Backend:** Creates record in PocketBase with organizationId
+5. **UI Update:** Refreshes list, shows success toast
+6. **Error Handling:** Displays error message if creation fails
+
+**Data Flow Diagram (Optional):**
+
+```
+┌─────────┐     ┌─────────────┐     ┌──────────────┐
+│ Plugin  │────>│ Window Bridge│────>│ Kernel/Host  │
+│ Component│    │ (publish)    │     │ Services     │
+└─────────┘     └─────────────┘     └──────────────┘
+                                            │
+                                            v
+                                      ┌──────────────┐
+                                      │ PocketBase   │
+                                      │ (API)        │
+                                      └──────────────┘
+```
+
+**State Management:**
+
+<!-- How is state managed? -->
+
+- [ ] Local component state (useState)
+- [ ] TanStack Query (server state)
+- [ ] Kernel state (useGlobalKernelState)
+- [ ] Channel bus (events)
+
+---
+
+## API & Data Requirements
+
+**PocketBase Collections (if creating new):**
+
+```javascript
+{
+  name: 'my_collection',
+  type: 'base',
+  fields: [
+    // Multi-tenancy required fields
+    { name: 'organizationId', type: 'relation', required: true },
+    { name: 'ownerId', type: 'relation', required: true },
+
+    // Your fields here
+    { name: 'title', type: 'text', required: true },
+    { name: 'description', type: 'text' },
+    { name: 'status', type: 'select', options: ['active', 'inactive'] },
+  ],
+
+  // Multi-tenancy API rules
+  listRule: '@request.auth.id != "" && organizationId = @request.auth.membership.organizations',
+  viewRule: '@request.auth.id != "" && organizationId = @request.auth.membership.organizations',
+  createRule: '@request.auth.id != "" && organizationId = @request.auth.membership.organizations',
+  updateRule: '@request.auth.id != "" && organizationId = @request.auth.membership.organizations && ownerId = @request.auth.id',
+  deleteRule: '@request.auth.id != "" && organizationId = @request.auth.membership.organizations && ownerId = @request.auth.id',
+}
+```
+
+**Custom Hooks to Create:**
+
+<!-- List data fetching and mutation hooks needed -->
+
+- `useMyItems()` - Fetch items for current organization
+- `useCreateMyItem()` - Create new item
+- `useUpdateMyItem()` - Update existing item
+- `useDeleteMyItem()` - Delete item
+
+---
+
+## Permissions & Security
+
+**Required Permissions (RBAC):**
+
+<!-- Define permissions needed for this feature -->
+
+| Permission | Resource | Action | Description |
+|------------|----------|--------|-------------|
+| `myplugin.read` | myplugin | read | View items |
+| `myplugin.write` | myplugin | write | Create/edit items |
+| `myplugin.delete` | myplugin | delete | Delete items |
+
+**Access Control:**
+
+- [ ] All pages require authentication
+- [ ] Certain actions require specific permissions
+- [ ] Data scoped to organization
+- [ ] Ownership verification (users can only edit their own items)
+
+---
+
+## Testing Strategy
+
+**Test Cases:**
+
+<!-- List scenarios that must be tested -->
+
+- [ ] User can view list of items
+- [ ] User can create new item
+- [ ] User can edit own item
+- [ ] User cannot edit others' items
+- [ ] User can delete own item
+- [ ] Form validation works
+- [ ] Toast notifications display
+- [ ] Organization isolation works (users only see their org's data)
+
+**Testing Commands:**
+
+```bash
+# Run tests
+pnpm test
+
+# E2E tests
+pnpm test:e2e
+
+# Type checking
+pnpm run typecheck
+```
+
+---
+
+## AI Instructions
+
+**IMPORTANT:** Read these instructions before starting work:
+
+### 1. DOCUMENTATION FIRST
+
+You **MUST** read the relevant documentation files before writing any code:
+
+1. **ALWAYS read** `/docs/framework/setup/00-index.md` first
+2. **Read files based on task type:**
+   - Creating plugin → Read `07-plugin-development.md`
+   - Adding UI components → Read `12-components-api.md`
+   - Working with hooks → Read `11-hooks-api.md`
+   - Deployment → Read `13-deployment-guide.md`
+3. **Follow established patterns** from Dashboard/Todo plugins
+
+### 2. MICROKERNEL ARCHITECTURE RULES
+
+**STRICT SEPARATION:**
+
+- **Framework (Kernel)** = Core services in `host/src/kernel/`
+- **Application Plugins** = Features in `packages/plugins/@lego/`
+
+**YOU CANNOT:**
+- Modify kernel code when working on application plugins
+- Create circular dependencies between host and plugins
+- Import directly from host kernel in plugins (use window bridge)
+
+**YOU MUST:**
+- Implement all features within plugin scope
+- Use window bridge for host communication: `window.__LEGO_CHANNEL_BUS__`
+- Read kernel state via: `window.__LEGO_KERNEL_STATE__`
+- Follow existing plugin structure exactly
+
+**IF KERNEL MODIFICATION IS NEEDED:**
+1. **STOP IMMEDIATELY**
+2. **Inform the user:** "This task requires Framework/Kernel changes"
+3. **Request permission** before proceeding
+4. **If approved:** Make kernel changes first, then plugin changes
+
+### 3. CODE ORGANIZATION
+
+**File Structure for New Plugin:**
+
+```
+packages/plugins/@lego/plugin-<name>/
+├── src/
+│   ├── components/       # React components
+│   ├── hooks/            # Data fetching hooks
+│   ├── pages/            # Page components
+│   ├── plugin.config.ts  # Plugin configuration
+│   ├── plugin.ts         # Entry point
+│   ├── types.ts          # TypeScript types
+│   ├── schemas.ts        # Zod validation schemas
+│   └── global.css        # Plugin styles
+├── package.json
+├── tsconfig.json
+├── modern.config.ts
+└── tailwind.config.ts
+```
+
+**Naming Conventions:**
+- Components: PascalCase (`MyComponent.tsx`)
+- Hooks: camelCase with 'use' prefix (`useMyData.ts`)
+- Types: PascalCase (`MyType`, `MyInterface`)
+- Files: kebab-case for non-TS (`my-file.css`)
+
+### 4. MULTI-TENANCY REQUIREMENTS
+
+**ALL data MUST be scoped to organization:**
+
+```typescript
+// ✅ CORRECT - Filter by organization
+const result = await pb.collection('items').getList(1, 50, {
+  filter: `organizationId = "${orgId}"`
+});
+
+// ❌ WRONG - No organization filter
+const result = await pb.collection('items').getList(1, 50);
+```
+
+**PocketBase collections MUST include:**
+- `organizationId` field (relation to organizations)
+- `ownerId` field (relation to users)
+- API rules with organization filtering
+
+### 5. TYPE SAFETY
+
+- **TypeScript strict mode** is required
+- Define all types in `types.ts`
+- Use Zod schemas for validation
+- No `any` types without justification
+
+### 6. ERROR HANDLING
+
+- **Always handle loading states** (show spinners/skeletons)
+- **Always handle error states** (show error messages)
+- **Use toast notifications** for user feedback
+- **Log errors** for debugging
+
+### 7. TESTING
+
+- Write unit tests for hooks and utilities
+- Write component tests for UI
+- Test multi-tenancy (org isolation)
+- Test permission checks
+
+### 8. CHECKPOINT DOCUMENTATION
+
+**You MUST create a checkpoint file for all work:**
+
+- Bugfixes → `/docs/checkpoints/bugfixes/<title>.md`
+- Features → `/docs/checkpoints/features/<title>.md`
+- Enhancements → `/docs/checkpoints/enhancements/<title>.md`
+
+Use the template from `/docs/checkpoints/.template.md`
+
+---
+
+## Additional Notes
+
+<!-- Any other context, constraints, or preferences -->
+
+- Preferred design style: (minimal, detailed, etc.)
+- Performance considerations:
+- Accessibility requirements:
+- Browser compatibility:
+- Other requirements:
+
+---
+
+## Session Checklist
+
+**Before starting work:**
+
+- [ ] All sections above are filled out
+- [ ] AI has read relevant documentation
+- [ ] Target scope is clear (Framework vs Application)
+- [ ] Dependencies are identified
+- [ ] UI/UX requirements are defined
+
+**During work:**
+
+- [ ] Following microkernel architecture rules
+- [ ] Using existing components and patterns
+- [ ] Writing tests as code is developed
+- [ ] Handling errors and loading states
+- [ ] Maintaining type safety
+
+**After completion:**
+
+- [ ] All acceptance criteria met
+- [ ] Tests passing
+- [ ] Checkpoint documentation created
+- [ ] Code follows framework patterns
+- [ ] Ready for review
+
+---
+
+## Quick Reference
+
+**Essential Files:**
+- Documentation Index: `/docs/framework/setup/00-index.md`
+- Plugin Development: `/docs/framework/setup/07-plugin-development.md`
+- Components API: `/docs/framework/setup/12-components-api.md`
+- Hooks API: `/docs/framework/setup/11-hooks-api.md`
+- Checkpoint Template: `/docs/checkpoints/.template.md`
+
+**Key Commands:**
+```bash
+# Development
+pnpm run dev:all              # Start all services
+pnpm run dev:host             # Start host only
+pnpm --filter './packages/plugins/@lego/plugin-<name>' dev
+
+# Building
+pnpm run build                # Build all
+pnpm --filter './packages/plugins/@lego/plugin-<name>' build
+
+# Testing
+pnpm test                     # Run all tests
+pnpm test:e2e                 # E2E tests
+pnpm test:coverage            # Coverage report
+
+# Type Checking
+pnpm run typecheck            # TypeScript validation
+```
+
+---
+
+**READY TO START:** When all sections are complete, share this file with the AI and begin the vibe coding session!