@objectql/create 1.0.0

package/templates/starter/src/modules/projects/projects.hook.ts

@@ -0,0 +1,339 @@
+import { ObjectHookDefinition } from '@objectql/types';
+import { Projects } from '../../types';
+
+/**
+ * Project Hooks - Comprehensive Example
+ * 
+ * This file demonstrates all major hook patterns according to the ObjectQL specification:
+ * 1. Data validation and defaulting (beforeCreate)
+ * 2. Query modification for security (beforeFind)
+ * 3. State transition validation (beforeUpdate)
+ * 4. Change tracking and notifications (afterUpdate)
+ * 5. Dependency checking (beforeDelete)
+ * 6. Side effects and cleanup (afterDelete)
+ */
+const hooks: ObjectHookDefinition<Projects> = {
+    
+    /**
+     * beforeCreate - Data Validation & Defaulting
+     * 
+     * Use case:
+     * - Set default values
+     * - Auto-assign ownership
+     * - Validate business rules
+     * - Check for duplicates
+     */
+    beforeCreate: async ({ data, user, api }) => {
+        // 1. Auto-assign owner if not specified
+        if (data && !data.owner && user?.id) {
+            console.log(`[Hook] Projects: Auto-assigning owner ${user.id}`);
+            data.owner = String(user.id);
+        }
+
+        // 2. Set default status if not provided
+        if (data && !data.status) {
+            data.status = 'planned';
+        }
+
+        // 3. Validate required fields
+        if (data && (!data.name || data.name.trim().length === 0)) {
+            throw new Error('Project name is required');
+        }
+
+        // 4. Validate name length
+        if (data && data.name && data.name.length > 100) {
+            throw new Error('Project name must be 100 characters or less');
+        }
+
+        // 5. Check for duplicate names (using API)
+        if (data && data.name) {
+            const existing = await api.count('projects', [['name', '=', data.name]]);
+            if (existing > 0) {
+                throw new Error(`A project named "${data.name}" already exists`);
+            }
+        }
+
+        // 6. Set initial budget if not provided
+        if (data && !data.budget) {
+            data.budget = 0;
+        }
+    },
+
+    /**
+     * afterCreate - Side Effects
+     * 
+     * Use case:
+     * - Send notifications
+     * - Create related records
+     * - Log audit trail
+     * - Trigger workflows
+     */
+    afterCreate: async ({ result, user, api, state }) => {
+        console.log(`[Hook] Projects: Project created - ${result?.name} by ${user?.id}`);
+        
+        // Example: Create a default task for new projects
+        // Uncomment if tasks object exists
+        /*
+        if (result) {
+            await api.create('tasks', {
+                name: 'Setup Project',
+                project_id: result._id,
+                status: 'pending',
+                description: 'Initial project setup task'
+            });
+        }
+        */
+    },
+
+    /**
+     * beforeFind - Query Filtering for Security
+     * 
+     * Use case:
+     * - Enforce multi-tenancy
+     * - Apply row-level security
+     * - Add default filters
+     * - Restrict data access based on user role
+     */
+    beforeFind: async ({ query, user, api }) => {
+        // Example: If not admin, restrict to own projects
+        // Uncomment to enable row-level security
+        /*
+        if (user && !user.isAdmin) {
+            // Add filter to only show projects owned by current user
+            if (!query.filters) {
+                query.filters = [];
+            }
+            query.filters.push(['owner', '=', user.id]);
+            console.log(`[Hook] Projects: Filtering to user ${user.id}'s projects`);
+        }
+        */
+        
+        // Example: Add default sort
+        if (!query.sort) {
+            query.sort = [{ field: 'created_at', direction: 'desc' }];
+        }
+    },
+
+    /**
+     * afterFind - Result Transformation
+     * 
+     * Use case:
+     * - Add computed fields
+     * - Mask sensitive data
+     * - Enrich data from external sources
+     * - Transform dates/formats
+     */
+    afterFind: async ({ result, user }) => {
+        // Example: Add computed progress field based on status
+        if (Array.isArray(result)) {
+            result.forEach((project: any) => {
+                switch (project.status) {
+                    case 'planned':
+                        project.progress = 0;
+                        break;
+                    case 'in_progress':
+                        project.progress = 50;
+                        break;
+                    case 'completed':
+                        project.progress = 100;
+                        break;
+                    default:
+                        project.progress = 0;
+                }
+            });
+        }
+    },
+
+    /**
+     * beforeUpdate - State Transition Validation
+     * 
+     * Use case:
+     * - Validate state machine transitions
+     * - Check permissions for specific updates
+     * - Validate budget changes
+     * - Track modifications
+     */
+    beforeUpdate: async ({ data, previousData, isModified, user, state }) => {
+        // 1. Check budget constraints
+        if (isModified('budget')) {
+            if (data && data.budget != undefined && data.budget < 0) {
+                throw new Error('Budget cannot be negative');
+            }
+            
+            if (data && data.budget != undefined && previousData && data.budget < (previousData.budget || 0)) {
+                console.warn(`[Hook] Projects: Budget reduced from ${previousData.budget} to ${data.budget}`);
+                
+                // Optional: Require approval for budget reduction
+                /*
+                if ((previousData.budget || 0) - data.budget > 10000) {
+                    throw new Error('Budget reductions over $10,000 require approval');
+                }
+                */
+            }
+        }
+
+        // 2. Validate status transitions
+        if (isModified('status') && previousData) {
+            const oldStatus = previousData.status;
+            const newStatus = data?.status;
+
+            // Define valid transitions
+            const validTransitions: Record<string, string[]> = {
+                'planned': ['in_progress'],
+                'in_progress': ['completed', 'planned'],  // Can go back to planning
+                'completed': []  // Cannot change from completed
+            };
+
+            if (oldStatus && newStatus) {
+                const allowed = validTransitions[oldStatus] || [];
+                if (!allowed.includes(newStatus)) {
+                    throw new Error(
+                        `Invalid status transition: cannot change from "${oldStatus}" to "${newStatus}"`
+                    );
+                }
+            }
+        }
+
+        // 3. Require end_date when marking as completed
+        if (isModified('status') && data?.status === 'completed') {
+            if (!data.end_date && !previousData?.end_date) {
+                throw new Error('End date is required when completing a project');
+            }
+        }
+
+        // 4. Store change summary in state for afterUpdate hook
+        if (isModified('status')) {
+            state.statusChanged = true;
+            state.oldStatus = previousData?.status;
+            state.newStatus = data?.status;
+        }
+    },
+
+    /**
+     * afterUpdate - Change Notifications & Side Effects
+     * 
+     * Use case:
+     * - Send notifications based on changes
+     * - Update related records
+     * - Trigger workflows
+     * - Log audit trail
+     */
+    afterUpdate: async ({ isModified, data, previousData, result, state, api, user }) => {
+        // 1. Notify on status change
+        if (state.statusChanged) {
+            console.log(
+                `[Hook] Projects: Status changed from "${state.oldStatus}" to "${state.newStatus}" by ${user?.id}`
+            );
+            
+            // Example: Create notification record
+            /*
+            if (data.status === 'completed' && previousData?.owner) {
+                await api.create('notifications', {
+                    user_id: previousData.owner,
+                    message: `Project "${result?.name}" has been completed!`,
+                    type: 'project_completed',
+                    link: `/projects/${result?._id}`
+                });
+            }
+            */
+        }
+
+        // 2. Notify on budget changes over threshold
+        if (isModified('budget') && previousData) {
+            const oldBudget = previousData.budget || 0;
+            const newBudget = data?.budget || 0;
+            const change = Math.abs(newBudget - oldBudget);
+            
+            if (change > 5000) {
+                console.log(
+                    `[Hook] Projects: Significant budget change detected: ${oldBudget} -> ${newBudget}`
+                );
+            }
+        }
+
+        // 3. Update related tasks when project is completed
+        /*
+        if (data.status === 'completed') {
+            await api.updateMany('tasks', 
+                { filters: [['project_id', '=', result._id]] },
+                { status: 'completed' }
+            );
+        }
+        */
+    },
+
+    /**
+     * beforeDelete - Dependency Checking
+     * 
+     * Use case:
+     * - Prevent deletion if dependencies exist
+     * - Check permissions
+     * - Validate business rules
+     */
+    beforeDelete: async ({ id, previousData, api, user }) => {
+        // 1. Prevent deletion of completed projects
+        if (previousData?.status === 'completed') {
+            throw new Error('Cannot delete completed projects. Please archive instead.');
+        }
+
+        // 2. Check for dependent tasks
+        /*
+        const taskCount = await api.count('tasks', [['project_id', '=', id]]);
+        
+        if (taskCount > 0) {
+            throw new Error(
+                `Cannot delete project: ${taskCount} tasks are still associated with it. ` +
+                'Please delete or reassign tasks first.'
+            );
+        }
+        */
+
+        // 3. Require admin permission for deletion
+        /*
+        if (!user?.isAdmin) {
+            throw new Error('Only administrators can delete projects');
+        }
+        */
+
+        console.log(`[Hook] Projects: Preparing to delete project ${id}`);
+    },
+
+    /**
+     * afterDelete - Cleanup & Side Effects
+     * 
+     * Use case:
+     * - Delete related records (cascade)
+     * - Clean up external resources
+     * - Send notifications
+     * - Log audit trail
+     */
+    afterDelete: async ({ id, previousData, api, user }) => {
+        console.log(`[Hook] Projects: Project deleted - ${previousData?.name} by ${user?.id}`);
+        
+        // Example: Clean up related data
+        /*
+        // Delete associated tasks
+        await api.deleteMany('tasks', {
+            filters: [['project_id', '=', id]]
+        });
+        
+        // Delete associated files from S3
+        if (previousData?.attachments) {
+            for (const attachment of previousData.attachments) {
+                await deleteFromS3(attachment.key);
+            }
+        }
+        
+        // Create audit log
+        await api.create('audit_logs', {
+            action: 'project_deleted',
+            entity_id: id,
+            entity_name: previousData?.name,
+            user_id: user?.id,
+            timestamp: new Date()
+        });
+        */
+    }
+};
+
+export default hooks;

package/templates/starter/src/modules/projects/projects.object.yml

@@ -0,0 +1,148 @@
+label: Project
+icon: building-line
+fields:
+  name:
+    type: text
+    required: true
+    index: true # Field-level index
+
+  status:
+    options:
+      - planned
+      - in_progress
+      - completed
+    defaultValue: planned
+    index: true
+
+  priority:
+    options:
+      - low
+      - normal
+      - high
+    defaultValue: normal
+
+  description:
+    type: textarea
+
+  owner:
+    type: text
+
+  budget:
+    type: currency
+
+  start_date:
+    type: date
+
+  end_date:
+    type: date
+  
+  approved_by:
+    type: text
+  
+  approved_at:
+    type: datetime
+  
+  approval_comment:
+    type: textarea
+
+indexes:
+  # Composite index for reporting
+  status_priority_idx:
+    fields: [status, priority]
+
+ai:
+  search:
+    enabled: true
+    fields: [name, description]
+    model: text-embedding-3-small
+
+actions:
+  # Record Actions (operate on specific records)
+  complete:
+    type: record
+    label: Complete Project
+    icon: checkbox-circle-line
+    confirm_text: "Are you sure you want to complete this project?"
+    params:
+      comment:
+        type: textarea
+        label: Completion Comment
+      completion_date:
+        type: date
+        label: Completion Date
+  
+  approve:
+    type: record
+    label: Approve Project
+    icon: shield-check-line
+    confirm_text: "Are you sure you want to approve this project?"
+    params:
+      comment:
+        type: textarea
+        required: true
+        label: Approval Comment
+        help_text: "Provide a reason for approving this project"
+  
+  clone:
+    type: record
+    label: Clone Project
+    icon: file-copy-line
+    description: Create a copy of this project
+    params:
+      new_name:
+        type: text
+        required: true
+        label: New Project Name
+      copy_tasks:
+        type: checkbox
+        label: Copy Associated Tasks
+        defaultValue: false
+
+  # Global Actions (operate on collections)
+  import_projects:
+    type: global
+    label: Import Projects
+    icon: download-line
+    internal: false
+    description: Import multiple projects from various sources
+    params:
+      source:
+        required: true
+        label: Import Source
+        options:
+          - csv
+          - json
+          - api
+      data:
+        type: textarea
+        label: JSON Data
+        help_text: "Paste JSON array of projects (optional if using file_url)"
+      file_url:
+        type: text
+        label: File URL
+        help_text: "URL to fetch data from (optional if using data field)"
+  
+  bulk_update_status:
+    type: global
+    label: Bulk Update Status
+    icon: edit-box-line
+    description: Update status for multiple projects at once
+    params:
+      project_ids:
+        type: textarea
+        required: true
+        label: Project IDs
+        help_text: "List of project IDs"
+      new_status:
+        required: true
+        label: New Status
+        options:
+          - planned
+          - in_progress
+          - completed
+  
+  generate_report:
+    type: global
+    label: Generate Project Report
+    icon: file-chart-line
+    description: Generate statistical report of all projects

package/templates/starter/src/modules/projects/projects.permission.yml

@@ -0,0 +1,141 @@
+name: projects_permission
+object: projects
+description: "Comprehensive access control rules for Project object"
+
+# Roles (defined in demo.app.yml, referenced here)
+# This list documents which system roles have permissions on this object
+roles:
+  - admin
+  - manager
+  - developer
+  - user
+  - viewer
+
+# Object-level permissions (CRUD)
+object_permissions:
+  create: [admin, manager]
+  read: [admin, manager, developer, user, viewer]
+  update: [admin, manager]
+  delete: [admin]
+  view_all: [admin]      # Admins can see all projects
+  modify_all: [admin]    # Admins can edit all projects
+
+# Field-level security
+field_permissions:
+  budget:
+    read: [admin, manager]
+    update: [admin]  # Only admin can change budget
+  
+  approved_by:
+    read: [admin, manager, user]
+    update: [] # Read-only, set by system/workflow
+  
+  approved_at:
+    read: [admin, manager, user]
+    update: []
+  
+  approval_comment:
+    read: [admin, manager, user]
+    update: [admin, manager]
+
+# Record-level rules for dynamic access control
+record_rules:
+  - name: owner_full_access
+    priority: 100
+    description: Project owner has full access to their projects
+    condition:
+      type: simple
+      field: owner
+      operator: "="
+      value: $current_user.id
+    permissions:
+      read: true
+      update: true
+      delete: true
+  
+  - name: public_read_access
+    priority: 10
+    description: Completed projects are publicly readable
+    condition:
+      type: simple
+      field: status
+      operator: "="
+      value: completed
+    permissions:
+      read: true
+      update: false
+      delete: false
+
+# Sharing rules
+sharing_rules:
+  - name: manual_share
+    type: manual
+    description: Users can manually share projects with team members
+    enabled: true
+    permissions:
+      read: true
+      update: false
+      delete: false
+
+# Action permissions
+action_permissions:
+  approve:
+    execute: [admin, manager]
+    conditions:
+      - field: status
+        operator: "="
+        value: in_progress
+  
+  complete:
+    execute: [admin, manager]
+  
+  clone:
+    execute: [admin, manager, developer]
+  
+  import_projects:
+    execute: [admin]
+    rate_limit:
+      requests_per_hour: 10
+  
+  bulk_update_status:
+    execute: [admin, manager]
+
+# View permissions
+view_permissions:
+  all_projects:
+    access: [admin, manager, developer, user, viewer]
+    field_restrictions:
+      budget:
+        visible_to: [admin, manager]
+
+# Row-level security
+row_level_security:
+  enabled: true
+  default_rule:
+    field: owner
+    operator: "="
+    value: $current_user.id
+  exceptions:
+    - role: admin
+      bypass: true
+    - role: manager
+      condition:
+        type: simple
+        field: status
+        operator: "!="
+        value: completed
+
+# Audit trail
+audit:
+  enabled: true
+  events:
+    - permission_grant
+    - permission_revoke
+    - access_denied
+    - sensitive_field_access
+  retention_days: 365
+  alerts:
+    - event: access_denied
+      threshold: 5
+      window_minutes: 10
+      notify: [admin]

package/templates/starter/src/modules/projects/projects.validation.yml

@@ -0,0 +1,37 @@
+name: projects_validation
+object: projects
+description: "Validation rules for Projects"
+
+rules:
+  - name: valid_date_range
+    type: cross_field
+    ai_context:
+      intent: "Ensure project timeline is valid"
+      business_rule: "Projects cannot end before they start"
+    rule:
+      field: end_date
+      operator: ">="
+      compare_to: start_date
+    message: "End Date must be after Start Date"
+
+  - name: positive_budget
+    type: field
+    rule:
+      field: budget
+      operator: ">="
+      value: 0
+    message: "Budget cannot be negative"
+
+  - name: comment_required_if_high_budget
+    type: conditional
+    description: "Description is required for high budget projects"
+    ai_context:
+      business_rule: "High value projects (>10k) must have a detailed description"
+    condition:
+        field: budget
+        operator: ">"
+        value: 10000
+    rule:
+        field: description
+        operator: "not_empty"
+    message: "Description is required for high budget projects (> $10,000)"

package/templates/starter/src/modules/tasks/tasks.data.yml

@@ -0,0 +1,23 @@
+- _id: TASK-001
+  name: "Design Homepage Mockups"
+  project: "PROJ-001"
+  due_date: "2024-12-31"
+  completed: false
+
+- _id: TASK-002
+  name: "Setup CI/CD Pipeline"
+  project: "PROJ-001"
+  due_date: "2024-11-15"
+  completed: true
+
+- _id: TASK-003
+  name: "Draft App Requirements"
+  project: "PROJ-002"
+  due_date: "2025-01-20"
+  completed: false
+
+- _id: TASK-004
+  name: "Choose Tech Stack"
+  project: "PROJ-002"
+  due_date: "2025-01-10"
+  completed: true