@objectql/create 4.0.1 → 4.0.2

package/templates/hello-world/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @example/hello-world
 
+## 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.2",
   "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,15 @@
 # @objectql/starter-basic
 
+## 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectql/example-project-tracker",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "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"

package/templates/starter/src/seed.ts

@@ -50,7 +50,7 @@ async function main() {
 
     console.log("Querying Tasks...");
     const tasks = await ctx.object('tasks').find({
-        filters: { project: projectId }
+        where: { project: projectId }
     });
 
     console.log("📊 Project Report:", JSON.stringify({ project, tasks }, null, 2));