@objectql/cli 1.8.4 → 1.9.1

package/templates/starter/src/modules/kitchen-sink/kitchen_sink.data.yml

@@ -0,0 +1,18 @@
+- simple_text: "Hello World"
+  long_text: |
+    This is a long text.
+    It spans multiple lines.
+  rich_content: "# Markdown Header\n\n- List Item 1\n- List Item 2"
+  count: 42
+  price: 99.99
+  progress: 0.75
+  is_active: true
+  due_date: "2024-12-31"
+  meeting_time: "2024-12-31T10:00:00Z"
+  status: "published"
+  tags: ["tech", "blog"]
+  email_address: "test@example.com"
+  website: "https://objectql.org"
+  metadata:
+    source: "seed_data"
+    version: 1

package/templates/starter/src/modules/kitchen-sink/kitchen_sink.object.yml

@@ -0,0 +1,156 @@
+label: "Kitchen Sink (All Fields)"
+description: "A demonstration of every supported field type in ObjectQL"
+icon: "layout-grid-line"
+
+fields:
+  # --- String Types ---
+  simple_text:
+    type: text
+    label: Simple Text
+    required: true
+    min_length: 3
+    max_length: 100
+    help_text: "Basic single-line text"
+
+  long_text:
+    type: textarea
+    label: Multi-line Text
+    rows: 4
+  
+  rich_content:
+    type: markdown
+    label: Markdown Content
+  
+  raw_html:
+    type: html
+    label: HTML Content
+    readonly: true # Usually HTML is generated or read-only
+
+  # --- Number Types ---
+  count:
+    type: number
+    label: Integer Count
+    scale: 0
+    
+  price:
+    type: currency
+    label: Price
+    currency: USD
+    scale: 2
+
+  progress:
+    type: percent
+    label: Progress
+    min: 0
+    max: 1
+    scale: 2 # 0.55 -> 55%
+
+  # --- Boolean ---
+  is_active:
+    type: boolean
+    label: Is Active
+    defaultValue: true
+
+  # --- Date & Time ---
+  due_date:
+    type: date
+    label: Due Date
+  
+  meeting_time:
+    type: datetime
+    label: Meeting (Date & Time)
+  
+  alarm:
+    type: time
+    label: Alarm Time
+
+  # --- Selection ---
+  status:
+    type: select
+    label: Status
+    options:
+      - label: Draft
+        value: draft
+      - label: Published
+        value: published
+      - label: Archived
+        value: archived
+    defaultValue: draft
+  
+  tags:
+    type: select
+    label: Tags
+    multiple: true
+    options:
+      - tech
+      - news
+      - blog # Simple string array shorthand
+
+  # --- Contact & Web ---
+  email_address:
+    type: email
+    label: Email
+  
+  phone_number:
+    type: phone
+    label: Phone
+  
+  website:
+    type: url
+    label: Website URL
+
+  # --- Media ---
+  profile_pic:
+    type: image
+    label: Avatar
+    multiple: false
+    max_size: 1048576  # 1MB
+  
+  attachment:
+    type: file
+    label: Attachment document
+  
+  gallery:
+    type: image
+    label: Image Gallery
+    multiple: true
+
+  # --- Security ---
+  secret_code:
+    type: password
+    label: Secret Code
+
+  # --- Advanced / Complex ---
+  coords:
+    type: location
+    label: GPS Coordinates
+  
+  metadata:
+    type: object
+    label: JSON Metadata
+  
+  embedding:
+    type: vector
+    label: Vector Embedding
+    dimension: 1536 # e.g. OpenAI ada-002
+
+  # --- Relationships ---
+  related_project:
+    type: lookup
+    label: Related Project
+    reference_to: projects
+  
+  # Note: master_detail requires this object to be the detail side
+  # parent_project:
+  #   type: master_detail
+  #   reference_to: projects
+
+  # --- Computed ---
+  # auto_id:
+  #   type: auto_number
+  #   prefix: "KS-"
+    
+  # calc_value:
+  #   type: formula
+  #   expression: "{count} * 10"
+    

package/templates/starter/src/modules/projects/project_approval.workflow.yml

@@ -0,0 +1,51 @@
+name: project_approval
+label: "High Budget Project Approval"
+type: approval
+object: projects
+description: "Approval process for high budget projects (> $50,000)"
+
+trigger:
+  event: create_or_update
+  conditions:
+    - field: budget
+      operator: ">"
+      value: 50000
+    - field: status
+      operator: "="
+      value: "planned"
+
+steps:
+  - name: manager_review
+    label: "Manager Review"
+    type: approval
+    
+    assignee:
+      type: role
+      role: manager
+    
+    actions:
+      approve:
+        label: "Approve"
+        next_step: finance_review
+      reject:
+        label: "Reject"
+        outcome: rejected
+
+  - name: finance_review
+    label: "Finance Review"
+    type: approval
+    
+    assignee:
+      type: role
+      role: finance_admin
+    
+    actions:
+      approve:
+        label: "Approve Funding"
+        outcome: approved
+        updates:
+           status: "in_progress"
+           approved_at: "$now"
+      reject: 
+        label: "Reject Funding"
+        outcome: rejected

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

@@ -0,0 +1,472 @@
+import { ActionDefinition } from '@objectql/types';
+import { Projects } from '../../types';
+
+/**
+ * Project Actions - Comprehensive Examples
+ * 
+ * This file demonstrates action patterns according to the ObjectQL specification:
+ * 1. Record actions (operate on specific records)
+ * 2. Global actions (operate on collections)
+ * 3. Input validation
+ * 4. Multi-step business logic
+ * 5. Error handling
+ */
+
+/**
+ * Input type for the complete action
+ */
+interface CompleteInput {
+    comment?: string;
+    completion_date?: Date;
+}
+
+/**
+ * complete - Record Action Example
+ * 
+ * Demonstrates:
+ * - Fetching and validating current state
+ * - Performing atomic updates
+ * - Returning structured results
+ * - Input parameter usage
+ */
+export const complete: ActionDefinition<Projects, CompleteInput> = {
+    handler: async ({ id, input, api, user }) => {
+        const { comment, completion_date } = input;
+        
+        console.log(`[Action] Completing project ${id} by ${user?.id}`);
+        
+        // 1. Validate - Fetch current state
+        const project = await api.findOne('projects', id!);
+        
+        if (!project) {
+            throw new Error('Project not found');
+        }
+        
+        if (project.status === 'completed') {
+            throw new Error('Project is already completed');
+        }
+        
+        // 2. Validate - Check if user has permission
+        /*
+        if (!user?.isAdmin && project.owner !== user?.id) {
+            throw new Error('Only the project owner or admin can complete the project');
+        }
+        */
+        
+        // 3. Perform update with atomic operation
+        const updateData: any = { 
+            status: 'completed',
+            end_date: completion_date || new Date()
+        };
+        
+        // Add completion comment to description
+        if (comment) {
+            updateData.description = project.description 
+                ? `${project.description}\n\n[Completed on ${new Date().toISOString()}]: ${comment}`
+                : `[Completed on ${new Date().toISOString()}]: ${comment}`;
+        }
+        
+        await api.update('projects', id!, updateData);
+        
+        // 4. Optional: Create completion record or notification
+        /*
+        await api.create('project_completions', {
+            project_id: id,
+            completed_by: user?.id,
+            completed_at: new Date(),
+            comment: comment
+        });
+        */
+        
+        // 5. Return structured result
+        return { 
+            success: true, 
+            message: "Project completed successfully",
+            project_id: id,
+            completed_at: updateData.end_date
+        };
+    }
+};
+
+/**
+ * Input type for the approve action
+ */
+interface ApproveInput {
+    comment: string;
+}
+
+/**
+ * approve - Record Action with State Transition
+ * 
+ * Demonstrates:
+ * - State machine validation
+ * - Required input parameters
+ * - Business logic enforcement
+ */
+export const approve: ActionDefinition<Projects, ApproveInput> = {
+    handler: async ({ id, input, api, user }) => {
+        const { comment } = input;
+        
+        // 1. Validate input
+        if (!comment || comment.trim().length === 0) {
+            throw new Error('Approval comment is required');
+        }
+        
+        // 2. Fetch and validate current state
+        const project = await api.findOne('projects', id!);
+        
+        if (!project) {
+            throw new Error('Project not found');
+        }
+        
+        if (project.status !== 'planned') {
+            throw new Error('Only projects in "planned" status can be approved');
+        }
+        
+        // 3. Check budget threshold
+        if (project.budget > 100000 && !user?.isAdmin) {
+            throw new Error('Projects with budget over $100,000 require admin approval');
+        }
+        
+        // 4. Perform approval
+        await api.update('projects', id!, {
+            status: 'in_progress',
+            approved_by: user?.id,
+            approved_at: new Date(),
+            approval_comment: comment
+        });
+        
+        // 5. Log approval
+        console.log(`[Action] Project ${project.name} approved by ${user?.id}`);
+        
+        return {
+            success: true,
+            message: 'Project approved and moved to in_progress',
+            new_status: 'in_progress'
+        };
+    }
+};
+
+/**
+ * Input type for clone action
+ */
+interface CloneInput {
+    new_name: string;
+    copy_tasks?: boolean;
+}
+
+/**
+ * clone - Record Action with Related Data
+ * 
+ * Demonstrates:
+ * - Creating new records based on existing ones
+ * - Copying related data
+ * - Complex multi-step operations
+ */
+export const clone: ActionDefinition<Projects, CloneInput> = {
+    handler: async ({ id, input, api, user }) => {
+        const { new_name, copy_tasks = false } = input;
+        
+        // 1. Validate input
+        if (!new_name || new_name.trim().length === 0) {
+            throw new Error('New project name is required');
+        }
+        
+        // 2. Fetch source project
+        const sourceProject = await api.findOne('projects', id!);
+        
+        if (!sourceProject) {
+            throw new Error('Source project not found');
+        }
+        
+        // 3. Create cloned project
+        const clonedData = {
+            name: new_name,
+            description: `Cloned from: ${sourceProject.name}\n\n${sourceProject.description || ''}`,
+            status: 'planned',  // Always start as planned
+            priority: sourceProject.priority,
+            owner: user?.id || sourceProject.owner,  // Assign to current user
+            budget: sourceProject.budget,
+            start_date: sourceProject.start_date
+            // Don't copy: end_date, completed status
+        };
+        
+        const newProject = await api.create('projects', clonedData);
+        
+        // 4. Optional: Copy related tasks
+        if (copy_tasks) {
+            /*
+            const tasks = await api.find('tasks', {
+                filters: [['project_id', '=', id]]
+            });
+            
+            for (const task of tasks) {
+                await api.create('tasks', {
+                    name: task.name,
+                    description: task.description,
+                    project_id: newProject._id,
+                    status: 'pending',  // Reset status
+                    priority: task.priority
+                });
+            }
+            */
+        }
+        
+        console.log(`[Action] Project cloned: ${sourceProject.name} -> ${new_name}`);
+        
+        return {
+            success: true,
+            message: 'Project cloned successfully',
+            original_id: id,
+            new_project_id: newProject._id,
+            tasks_copied: copy_tasks
+        };
+    }
+};
+
+/**
+ * Input type for bulk import
+ */
+interface ImportProjectsInput {
+    source: 'csv' | 'json' | 'api';
+    data?: any[];
+    file_url?: string;
+}
+
+/**
+ * import_projects - Global Action Example
+ * 
+ * Demonstrates:
+ * - Batch operations
+ * - Data transformation
+ * - Error collection
+ * - Progress reporting
+ */
+export const import_projects: ActionDefinition<Projects, ImportProjectsInput> = {
+    handler: async ({ input, api, user }) => {
+        const { source, data, file_url } = input;
+        
+        console.log(`[Action] Importing projects from ${source} by ${user?.id}`);
+        
+        // 1. Validate input
+        if (!data && !file_url) {
+            throw new Error('Either data array or file_url must be provided');
+        }
+        
+        // 2. Fetch data based on source
+        let projectsData: any[] = data || [];
+        
+        if (file_url) {
+            // Example: Fetch from URL
+            /*
+            const response = await fetch(file_url);
+            projectsData = await response.json();
+            */
+            throw new Error('file_url import not yet implemented');
+        }
+        
+        // 3. Validate and import each project
+        const results = {
+            successCount: 0,
+            failed: 0,
+            errors: [] as any[]
+        };
+        
+        for (let i = 0; i < projectsData.length; i++) {
+            const projectData = projectsData[i];
+            
+            try {
+                // Validate required fields
+                if (!projectData.name) {
+                    throw new Error('Project name is required');
+                }
+                
+                // Set defaults
+                const importData = {
+                    name: projectData.name,
+                    description: projectData.description || '',
+                    status: projectData.status || 'planned',
+                    priority: projectData.priority || 'normal',
+                    budget: projectData.budget || 0,
+                    owner: projectData.owner || user?.id,
+                    start_date: projectData.start_date
+                };
+                
+                // Create project
+                await api.create('projects', importData);
+                results.successCount++;
+                
+            } catch (error: any) {
+                results.failed++;
+                results.errors.push({
+                    row: i + 1,
+                    name: projectData.name || 'Unknown',
+                    error: error.message
+                });
+            }
+        }
+        
+        console.log(`[Action] Import completed: ${results.successCount} succeeded, ${results.failed} failed`);
+        
+        return {
+            success: results.failed === 0,
+            message: `Imported ${results.successCount} projects, ${results.failed} failed`,
+            ...results
+        };
+    }
+};
+
+/**
+ * Input type for bulk update
+ */
+interface BulkUpdateStatusInput {
+    project_ids: string[];
+    new_status: 'planned' | 'in_progress' | 'completed';
+}
+
+/**
+ * bulk_update_status - Global Action for Batch Updates
+ * 
+ * Demonstrates:
+ * - Operating on multiple records
+ * - Validation across multiple items
+ * - Transactional operations (if supported)
+ */
+export const bulk_update_status: ActionDefinition<Projects, BulkUpdateStatusInput> = {
+    handler: async ({ input, api, user }) => {
+        const { project_ids, new_status } = input;
+        
+        // 1. Validate input
+        if (!project_ids || project_ids.length === 0) {
+            throw new Error('At least one project ID must be provided');
+        }
+        
+        if (project_ids.length > 100) {
+            throw new Error('Cannot update more than 100 projects at once');
+        }
+        
+        // 2. Update each project
+        // Note: This uses an N+1 query pattern (fetching each project individually)
+        // For production with large batches, consider fetching all projects at once:
+        // const projects = await api.find('projects', { filters: [['_id', 'in', project_ids]] });
+        // However, for this example with a 100-project limit, the current approach
+        // provides clearer per-record validation and error handling.
+        const results = {
+            updated: 0,
+            skipped: 0,
+            errors: [] as any[]
+        };
+        
+        for (const id of project_ids) {
+            try {
+                const project = await api.findOne('projects', id);
+                
+                if (!project) {
+                    results.errors.push({
+                        project_id: id,
+                        error: 'Project not found'
+                    });
+                    results.skipped++;
+                    continue;
+                }
+                
+                // Validate transition (simplified)
+                if (project.status === 'completed' && new_status !== 'completed') {
+                    results.errors.push({
+                        project_id: id,
+                        name: project.name,
+                        error: 'Cannot change status of completed projects'
+                    });
+                    results.skipped++;
+                    continue;
+                }
+                
+                // Perform update
+                await api.update('projects', id, { status: new_status });
+                results.updated++;
+                
+            } catch (error: any) {
+                results.errors.push({
+                    project_id: id,
+                    error: error.message
+                });
+                results.skipped++;
+            }
+        }
+        
+        console.log(`[Action] Bulk update: ${results.updated} updated, ${results.skipped} skipped`);
+        
+        return {
+            success: results.skipped === 0,
+            message: `Updated ${results.updated} projects, skipped ${results.skipped}`,
+            ...results
+        };
+    }
+};
+
+/**
+ * generate_report - Global Action for Reporting
+ * 
+ * Demonstrates:
+ * - Aggregation and analysis
+ * - Data collection across records
+ * - Computed results
+ */
+export const generate_report: ActionDefinition<Projects, {}> = {
+    handler: async ({ api, user }) => {
+        console.log(`[Action] Generating project report for ${user?.id}`);
+        
+        // 1. Fetch all projects (or apply filters)
+        const allProjects = await api.find('projects', {});
+        
+        // 2. Calculate statistics
+        const report = {
+            total_projects: allProjects.length,
+            by_status: {
+                planned: 0,
+                in_progress: 0,
+                completed: 0
+            },
+            by_priority: {
+                low: 0,
+                normal: 0,
+                high: 0
+            },
+            total_budget: 0,
+            average_budget: 0,
+            generated_at: new Date(),
+            generated_by: user?.id
+        };
+        
+        // 3. Aggregate data
+        allProjects.forEach(project => {
+            // Count by status
+            const status = project.status || 'planned';
+            if (status in report.by_status) {
+                report.by_status[status as keyof typeof report.by_status]++;
+            }
+            
+            // Count by priority
+            const priority = project.priority || 'normal';
+            if (priority in report.by_priority) {
+                report.by_priority[priority as keyof typeof report.by_priority]++;
+            }
+            
+            // Sum budget
+            report.total_budget += project.budget || 0;
+        });
+        
+        // 4. Calculate averages
+        report.average_budget = allProjects.length > 0 
+            ? report.total_budget / allProjects.length 
+            : 0;
+        
+        console.log(`[Action] Report generated: ${report.total_projects} projects analyzed`);
+        
+        return {
+            success: true,
+            message: 'Report generated successfully',
+            report
+        };
+    }
+};

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

@@ -0,0 +1,13 @@
+- _id: PROJ-001
+  name: "Website Redesign (From Data)"
+  description: "Initial data loaded from projects.data.yml"
+  status: "in_progress"
+  priority: "high"
+  owner: "u-123"
+
+- _id: PROJ-002
+  name: "Mobile App (From Data)"
+  description: "Initial data loaded from projects.data.yml"
+  status: "planned"
+  priority: "medium"
+  owner: "u-999"