@objectql/create 4.0.1 → 4.0.3

package/templates/enterprise/src/modules/project/project_task.object.yml

@@ -1,13 +1,26 @@
+# File: project_task.object.yml
+# Object name is inferred from filename as 'project_task'
 label: Task
 description: Project task or work item
 icon: task-line
 
+ai_context:
+  intent: "Track individual work items and tasks within projects"
+  domain: project_management
+  aliases: [task, work item, issue]
+  common_queries:
+    - "Show my assigned tasks"
+    - "Find overdue tasks"
+    - "List tasks by project"
+
 fields:
   name:
     type: text
     required: true
     label: Task Name
     index: true
+    ai_context:
+      intent: "Brief description of the task"
   
   project:
     type: lookup
@@ -15,73 +28,121 @@ fields:
     label: Project
     required: true
     index: true
+    ai_context:
+      intent: "Parent project containing this task"
+      semantic_type: hierarchy
   
   parent_task:
     type: lookup
     reference_to: project_task
     label: Parent Task
     index: true
+    ai_context:
+      intent: "Parent task for hierarchical task structure"
+      semantic_type: hierarchy
   
   description:
     type: textarea
     label: Description
+    ai_context:
+      intent: "Detailed task requirements and acceptance criteria"
   
   status:
     type: select
+    label: Task Status
     options:
-      - todo
-      - in_progress
-      - in_review
-      - blocked
-      - completed
+      - label: To Do
+        value: todo
+      - label: In Progress
+        value: in_progress
+      - label: In Review
+        value: in_review
+      - label: Blocked
+        value: blocked
+      - label: Completed
+        value: completed
     defaultValue: todo
     required: true
     index: true
+    ai_context:
+      intent: "Current state of task execution"
+      is_state_machine: true
+      transitions:
+        todo: [in_progress]
+        in_progress: [in_review, blocked, completed]
+        in_review: [in_progress, completed]
+        blocked: [in_progress, todo]
+        completed: []
   
   priority:
     type: select
+    label: Priority
     options:
-      - low
-      - medium
-      - high
-      - critical
+      - label: Low
+        value: low
+      - label: Medium
+        value: medium
+      - label: High
+        value: high
+      - label: Critical
+        value: critical
     defaultValue: medium
     index: true
+    ai_context:
+      intent: "Task urgency and importance level"
+      selection_guidance: "Critical for blockers; High for urgent items"
   
   assigned_to:
     type: lookup
     reference_to: user
     label: Assigned To
     index: true
+    ai_context:
+      intent: "User responsible for completing this task"
+      semantic_type: ownership
+      selection_guidance: "Active team members with relevant skills"
   
   due_date:
     type: date
     label: Due Date
     index: true
+    ai_context:
+      intent: "Target completion deadline"
   
   completed_date:
     type: datetime
     label: Completion Date
+    ai_context:
+      intent: "Actual completion timestamp for reporting"
   
   estimated_hours:
     type: number
     label: Estimated Hours
     scale: 2
+    ai_context:
+      intent: "Planned effort for capacity planning"
   
   actual_hours:
     type: number
     label: Actual Hours
     scale: 2
+    ai_context:
+      intent: "Actual time spent for productivity tracking"
   
   milestone:
     type: lookup
     reference_to: project_milestone
     label: Milestone
     index: true
+    ai_context:
+      intent: "Associated milestone for tracking progress"
+      semantic_type: association
   
   tags:
     type: text
     label: Tags
+    ai_context:
+      intent: "Categorization labels for filtering and organization"
 
 indexes:
   # For project task list

package/templates/enterprise/src/modules/project/project_timesheet_entry.object.yml

@@ -1,7 +1,18 @@
+# File: project_timesheet_entry.object.yml
+# Object name is inferred from filename as 'project_timesheet_entry'
 label: Timesheet Entry
 description: Time entry for project tasks
 icon: time-line
 
+ai_context:
+  intent: "Track time spent on project tasks for billing and productivity"
+  domain: project_management
+  aliases: [time entry, timesheet, time log]
+  common_queries:
+    - "Show time entries by project"
+    - "Find billable hours by employee"
+    - "List time entries for approval"
+
 fields:
   employee:
     type: lookup
@@ -9,6 +20,9 @@ fields:
     label: Employee
     required: true
     index: true
+    ai_context:
+      intent: "Employee who performed the work"
+      semantic_type: association
   
   project:
     type: lookup
@@ -16,12 +30,18 @@ fields:
     label: Project
     required: true
     index: true
+    ai_context:
+      intent: "Project this time is charged to"
+      semantic_type: hierarchy
   
   task:
     type: lookup
     reference_to: project_task
     label: Task
     index: true
+    ai_context:
+      intent: "Specific task this time is charged to"
+      semantic_type: association
   
   work_date:
     type: date
@@ -50,17 +70,32 @@ fields:
   status:
     type: select
     options:
-      - draft
-      - submitted
-      - approved
-      - rejected
+      - label: Draft
+        value: draft
+      - label: Submitted
+        value: submitted
+      - label: Approved
+        value: approved
+      - label: Rejected
+        value: rejected
     defaultValue: draft
     index: true
+    ai_context:
+      intent: "Approval workflow state"
+      is_state_machine: true
+      transitions:
+        draft: [submitted]
+        submitted: [approved, rejected]
+        approved: []
+        rejected: [draft]
   
   approved_by:
     type: lookup
     reference_to: user
     label: Approved By
+    ai_context:
+      intent: "Manager who approved this time entry"
+      semantic_type: association
   
   approved_at:
     type: datetime

package/templates/enterprise/src/plugins/audit/audit.plugin.ts

@@ -6,38 +6,22 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-// Import RuntimePlugin types from @objectql/core instead of @objectql/runtime
+// Import ObjectQLPlugin types from @objectql/core instead of @objectstack/runtime
 // to avoid ESM/CJS compatibility issues
-interface RuntimeContext {
-    engine: any; // ObjectStackKernel
-}
+type RuntimeContext = any;
 
-interface RuntimePlugin {
+interface ObjectQLPlugin {
     name: string;
-    install?: (ctx: RuntimeContext) => void | Promise<void>;
-    onStart?: (ctx: RuntimeContext) => void | Promise<void>;
+    init: (ctx: any) => void | Promise<void>;
 }
 
-const AuditLogPlugin: RuntimePlugin = {
+const AuditLogPlugin: ObjectQLPlugin = {
     name: 'audit-log',
     
-    async install(ctx: RuntimeContext) {
-        console.log('[AuditLogPlugin] Installing...');
+    async init(ctx: any) {
+        console.log('[AuditLogPlugin] Init...');
         // Plugin installation logic here
-    },
-    
-    async onStart(ctx: RuntimeContext) {
-        console.log('[AuditLogPlugin] Starting...');
-        
-        // TODO: Register event handlers using the runtime context
-        // The RuntimeContext provides:
-        // - ctx.engine for accessing the kernel
-        
-        // For now, we'll just log that the plugin is started
-        console.log('[AuditLogPlugin] Plugin started');
-        
-        // Note: The new plugin system uses RuntimeContext instead of PluginContextData
-        // This will need to be enhanced when the full events API is available
+        console.log('[AuditLogPlugin] Plugin initialized');
     }
 };
 

package/templates/enterprise/src/plugins/audit/note.object.yml

@@ -1,3 +1,20 @@
+# File: note.object.yml
+# Object name is inferred from filename as 'note'
+label: Note
+description: Audit note or comment
+icon: file-text-line
+
+ai_context:
+  intent: "Track audit notes and comments on records"
+  domain: audit
+  aliases: [note, comment, audit log]
+  common_queries:
+    - "Show recent notes"
+    - "Find notes by user"
+    - "List notes on a record"
+
 fields:
   content:
     type: text
+    ai_context:
+      intent: "Note content or comment text"

package/templates/hello-world/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @example/hello-world
 
+## 4.0.3
+
+### Patch Changes
+
+- Updated dependencies
+  - @objectql/core@4.0.3
+  - @objectql/driver-sql@4.0.3
+
+## 4.0.2
+
+### Patch Changes
+
+- Updated dependencies
+  - @objectql/core@4.0.2
+  - @objectql/driver-sql@4.0.2
+
 ## 4.0.1
 
 ### Patch Changes

package/templates/hello-world/README.md

@@ -1,11 +1,51 @@
 # Hello ObjectQL
 
-This is the simplest possible example of **ObjectQL**.
+This is the simplest possible example of **ObjectQL** following the **latest ObjectStack specification** (v4.0+).
 
-It demonstrates:
-1.  **Zero Config:** No YAML files or server setup required.
-2.  **In-Memory SQL:** Uses SQLite in memory, so no database installation is needed.
-3.  **Inline Schema:** Defines the data model directly in code.
+## What it demonstrates
+
+1.  **Zero Config:** No YAML files or server setup required
+2.  **In-Memory SQL:** Uses SQLite in memory, so no database installation is needed
+3.  **Inline Schema:** Defines the data model directly in code using programmatic API
+4.  **Latest Spec Compliance:**
+    - Label/value format for select options
+    - Explicit field labels for AI-friendly metadata
+    - Proper field type declarations
+
+## Key Concepts
+
+### Metadata Definition Approaches
+
+**Programmatic (This Example):**
+```typescript
+app.registerObject({
+  name: 'deal',  // Required when using code
+  fields: {
+    stage: { 
+      type: 'select',
+      options: [
+        { label: 'New', value: 'new' },  // ✅ Latest spec format
+        { label: 'Negotiation', value: 'negotiation' }
+      ]
+    }
+  }
+});
+```
+
+**YAML-based (Recommended for Production):**
+```yaml
+# File: deal.object.yml
+# NO 'name:' field needed - inferred from filename! ✅
+label: Deal
+fields:
+  stage:
+    type: select
+    options:
+      - label: New
+        value: new
+      - label: Negotiation
+        value: negotiation
+```
 
 ## How to Run
 
@@ -16,14 +56,37 @@ Since you are in the monorepo, simply run:
 pnpm install
 
 # Run the script
-cd examples/starters/hello-world
+cd examples/quickstart/hello-world
 pnpm start
 ```
 
 ## What you see
 
 The script will:
-1.  Initialize the ObjectQL engine.
-2.  Create a `deal` object definition on the fly.
-3.  Insert a record into the in-memory SQLite database.
-4.  Query it back and print the result.
+1.  Initialize the ObjectQL engine with an in-memory SQLite driver
+2.  Create a `deal` object definition programmatically
+3.  Insert a record into the database
+4.  Query it back and print the result
+
+## Expected Output
+
+```
+🚀 Starting ObjectQL Hello World...
+Creating a new Deal...
+✅ Deals found in database: [
+  {
+    _id: '...',
+    title: 'Enterprise Contract',
+    amount: 50000,
+    stage: 'new',
+    created_at: '...',
+    updated_at: '...'
+  }
+]
+```
+
+## Next Steps
+
+- See [Project Tracker Example](../../showcase/project-tracker/) for YAML-based metadata
+- Read the [Metadata Standard Spec](https://protocol.objectstack.ai) from @objectstack/spec
+- Explore the [ObjectQL Documentation](../../../content/docs/)

package/templates/hello-world/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectql/example-hello-world",
-  "version": "4.0.1",
+  "version": "4.0.3",
   "private": true,
   "repository": {
     "type": "git",

package/templates/hello-world/src/index.ts

@@ -26,14 +26,26 @@ async function main() {
     }
   });
   
-  // 3. Define Metadata Inline
+  // 3. Define Metadata Inline (Following Latest ObjectStack Specification)
+  // Note: When using registerObject(), the 'name' is required in code
+  // When using YAML files, the name is inferred from filename (e.g., deal.object.yml)
   app.registerObject({
-    name: 'deal',
+    name: 'deal',  // Required for programmatic registration
+    label: 'Deal',  // Human-readable label
     fields: {
-      title: { type: 'text', required: true },
-      amount: { type: 'currency' },
+      title: { 
+        type: 'text', 
+        required: true,
+        label: 'Deal Title'
+      },
+      amount: { 
+        type: 'currency',
+        label: 'Deal Amount'
+      },
       stage: { 
-        type: 'select', 
+        type: 'select',
+        label: 'Deal Stage',
+        // Options use label/value format (ObjectStack spec v4.0+)
         options: [
             { label: 'New', value: 'new' },
             { label: 'Negotiation', value: 'negotiation' },

package/templates/starter/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @objectql/starter-basic
 
+## 4.0.3
+
+### Patch Changes
+
+- Updated dependencies
+  - @objectql/core@4.0.3
+  - @objectql/driver-sql@4.0.3
+  - @objectql/platform-node@4.0.3
+  - @objectql/types@4.0.3
+
+## 4.0.2
+
+### Patch Changes
+
+- Updated dependencies
+  - @objectql/core@4.0.2
+  - @objectql/driver-sql@4.0.2
+  - @objectql/platform-node@4.0.2
+  - @objectql/types@4.0.2
+
 ## 4.0.1
 
 ### Patch Changes

package/templates/starter/jest.config.js

@@ -13,10 +13,18 @@ module.exports = {
   moduleNameMapper: {
   },
   transform: {
-    '^.+\\.ts$': ['ts-jest', {
+    '^.+\\.(t|j)sx?$': ['ts-jest', {
       isolatedModules: true,
+      tsconfig: {
+        esModuleInterop: true,
+        allowSyntheticDefaultImports: true,
+        allowJs: true,
+      }
     }],
   },
+  transformIgnorePatterns: [
+    "/node_modules/(?!(@objectstack|.pnpm))"
+  ],
   collectCoverageFrom: [
     'src/**/*.ts',
     '!src/**/*.d.ts',

package/templates/starter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectql/example-project-tracker",
-  "version": "4.0.1",
+  "version": "4.0.3",
   "description": "ObjectQL Basic Example Project",
   "private": true,
   "keywords": [

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

@@ -1,49 +1,108 @@
+# File: projects.object.yml
+# Object name is inferred from filename as 'projects'
 label: Project
 icon: building-line
+
+ai_context:
+  intent: "Track and manage software development projects"
+  domain: project_management
+  aliases: [project, initiative]
+  common_queries:
+    - "Find active projects"
+    - "Show projects by priority"
+    - "List projects with high budget"
+
 fields:
   name:
     type: text
     required: true
+    label: Project Name
     index: true # Field-level index
+    ai_context:
+      intent: "Primary identifier for the project"
+      examples: ["Website Redesign", "Mobile App v2.0"]
 
   status:
+    type: select
+    label: Project Status
     options:
-      - planned
-      - in_progress
-      - completed
+      - label: Planned
+        value: planned
+      - label: In Progress
+        value: in_progress
+      - label: Completed
+        value: completed
     defaultValue: planned
     index: true
+    ai_context:
+      intent: "Track project lifecycle stage"
+      is_state_machine: true
+      transitions:
+        planned: [in_progress, completed]
+        in_progress: [completed, planned]
+        completed: []
 
   priority:
+    type: select
+    label: Priority Level
     options:
-      - low
-      - normal
-      - high
+      - label: Low
+        value: low
+      - label: Normal
+        value: normal
+      - label: High
+        value: high
     defaultValue: normal
+    ai_context:
+      intent: "Prioritize project execution order"
+      selection_guidance: "High priority for urgent or critical projects"
 
   description:
     type: textarea
+    label: Project Description
+    ai_context:
+      intent: "Detailed project overview and objectives"
 
   owner:
     type: text
+    label: Project Owner
+    ai_context:
+      intent: "Person responsible for project success"
+      semantic_type: ownership
 
   budget:
     type: currency
+    label: Project Budget
+    ai_context:
+      intent: "Allocated financial resources"
+      validation_notes: "Must be non-negative; >$10k requires detailed description"
 
   start_date:
     type: date
+    label: Start Date
+    ai_context:
+      intent: "Project commencement date"
 
   end_date:
     type: date
+    label: End Date
+    ai_context:
+      intent: "Target completion date"
+      validation_notes: "Must be on or after start_date"
   
   approved_by:
     type: text
+    label: Approved By
+    ai_context:
+      intent: "Approver identity for audit trail"
   
   approved_at:
     type: datetime
+    label: Approval Timestamp
   
   approval_comment:
     type: textarea
+    label: Approval Comment
 
 indexes:
   # Composite index for reporting

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

@@ -1,5 +1,5 @@
-name: projects_validation
-object: projects
+# File: projects.validation.yml
+# Object is inferred from filename as 'projects'
 description: "Validation rules for Projects"
 
 rules:
@@ -8,25 +8,33 @@ rules:
     ai_context:
       intent: "Ensure project timeline is valid"
       business_rule: "Projects cannot end before they start"
+      rationale: "Maintaining data integrity for project scheduling"
     rule:
       field: end_date
       operator: ">="
       compare_to: start_date
-    message: "End Date must be after Start Date"
+    message: "End Date must be on or after Start Date"
+    error_code: "INVALID_DATE_RANGE"
 
   - name: positive_budget
     type: field
+    ai_context:
+      intent: "Prevent negative budget values"
+      business_rule: "Project budget must be zero or positive"
     rule:
       field: budget
       operator: ">="
       value: 0
     message: "Budget cannot be negative"
+    error_code: "NEGATIVE_BUDGET"
 
   - 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"
+      intent: "Ensure governance for high-value projects"
+      business_rule: "High value projects (>$10k) must have a detailed description for stakeholder transparency"
+      rationale: "Projects over $10,000 require executive oversight and clear documentation"
     condition:
         field: budget
         operator: ">"
@@ -35,3 +43,4 @@ rules:
         field: description
         operator: "not_empty"
     message: "Description is required for high budget projects (> $10,000)"
+    error_code: "HIGH_BUDGET_REQUIRES_DESCRIPTION"