@objectql/cli 1.7.2 → 1.8.0

package/AI_TUTORIAL.md

@@ -0,0 +1,144 @@
+# AI-Powered Application Generation - Tutorial
+
+This tutorial will guide you through using ObjectQL's AI-powered features to generate and validate enterprise applications.
+
+## Prerequisites
+
+1. Install ObjectQL CLI globally:
+```bash
+npm install -g @objectql/cli
+```
+
+2. Get an OpenAI API key from [OpenAI Platform](https://platform.openai.com/)
+
+3. Set your API key as an environment variable:
+```bash
+export OPENAI_API_KEY=sk-your-api-key-here
+```
+
+## Tutorial 1: Generate a Simple Task Management System
+
+### Step 1: Generate the Application
+
+Use the AI generator to create a task management system:
+
+```bash
+objectql ai generate \
+  -d "A task management system with projects and tasks. Projects should have a name, description, status (planning, active, completed), and owner. Tasks belong to projects and have a title, description, priority (low, medium, high), status (todo, in_progress, done), and assignee." \
+  -t complete \
+  -o ./my-task-app
+```
+
+### Step 2: Review Generated Files
+
+The AI will generate several metadata files:
+
+```bash
+cd my-task-app
+ls -la
+
+# Expected output:
+# project.object.yml
+# task.object.yml
+# project.validation.yml (optional)
+# task.validation.yml (optional)
+```
+
+### Step 3: Validate the Generated Metadata
+
+Validate the generated files to ensure they follow ObjectQL standards:
+
+```bash
+objectql ai validate .
+```
+
+The validator will check for:
+- YAML syntax errors
+- ObjectQL specification compliance
+- Business logic consistency
+- Data modeling best practices
+- Potential security issues
+
+### Step 4: Test the Application
+
+Start a development server to test your application:
+
+```bash
+objectql serve --dir .
+```
+
+Visit `http://localhost:3000` to interact with your application through the API.
+
+## Tutorial 2: Generate an Enterprise CRM System
+
+### Step 1: Generate with Detailed Requirements
+
+For more complex applications, provide detailed requirements:
+
+```bash
+objectql ai generate \
+  -d "A comprehensive CRM system with the following modules:
+
+1. Account Management: Companies with name, industry, revenue, employee count, and status
+2. Contact Management: People working at accounts with name, email, phone, position, and role
+3. Lead Management: Potential customers with source, qualification status, and score
+4. Opportunity Management: Sales opportunities with amount, stage, probability, close date
+5. Activity Tracking: Meetings, calls, emails associated with accounts/contacts
+
+Include proper relationships:
+- Contacts belong to accounts
+- Opportunities belong to accounts
+- Activities link to accounts, contacts, or opportunities
+- Include validation rules for data quality
+- Add status transitions for leads and opportunities" \
+  -t complete \
+  -o ./crm-system
+```
+
+### Step 2: Review and Customize
+
+```bash
+cd crm-system
+ls -la
+
+# Review generated files:
+# - account.object.yml
+# - contact.object.yml
+# - lead.object.yml
+# - opportunity.object.yml
+# - activity.object.yml
+# - Various .validation.yml files
+```
+
+Edit any file to customize fields, validation rules, or relationships.
+
+### Step 3: Validate
+
+```bash
+objectql ai validate .
+```
+
+Address any warnings or errors identified by the AI validator.
+
+### Step 4: Generate TypeScript Types
+
+Generate TypeScript interfaces for type-safe development:
+
+```bash
+objectql generate -s . -o ./types
+```
+
+## Tutorial 3: Using the AI Chat Assistant
+
+### Interactive Help
+
+Get help with ObjectQL concepts:
+
+```bash
+objectql ai chat
+```
+
+Example conversation:
+
+```
+You: How do I create a many-to-many relationship?

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @objectql/cli
 
+## 1.8.0
+
+### Minor Changes
+
+- Release minor version 1.8.0
+
+### Patch Changes
+
+- Updated dependencies
+  - @objectql/core@1.8.0
+  - @objectql/driver-sql@2.0.0
+  - @objectql/server@2.0.0
+  - @objectql/types@1.8.0
+  - @objectql/platform-node@1.8.0
+
+## 1.7.3
+
+### Patch Changes
+
+- Release patch version 1.7.3 with latest improvements and bug fixes
+- Updated dependencies
+  - @objectql/core@1.7.3
+  - @objectql/driver-sql@1.7.3
+  - @objectql/server@1.7.3
+  - @objectql/types@1.7.3
+  - @objectql/platform-node@1.7.3
+
 ## 1.7.2
 
 ### Patch Changes

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 ObjectQL Contributors
+Copyright (c) 2026 ObjectQL Contributors (https://github.com/objectql)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -12,6 +12,138 @@ pnpm add -D @objectql/cli
 
 ## Commands
 
+### AI-Powered Features
+
+The `ai` command provides AI-powered application generation and assistance. **By default, it starts in interactive conversational mode** for the best experience.
+
+#### Interactive Mode (Default)
+
+Simply type `objectql ai` to start building your application through conversation.
+
+```bash
+# Start interactive conversational builder (most common use case)
+objectql ai
+
+# Specify output directory
+objectql ai ./src/my-app
+```
+
+The interactive mode:
+- Guides you step-by-step through application creation
+- Lets you describe what you want in natural language
+- Generates metadata, TypeScript implementations, and tests
+- Allows iterative refinement through dialogue
+- Provides suggestions for next steps
+
+---
+
+#### One-Shot Generation
+
+For quick, non-interactive generation from a single description.
+
+```bash
+# Generate from a description
+objectql ai generate -d "A task management system with projects and tasks"
+
+# Generate complete enterprise application
+objectql ai generate -d "CRM with customers, contacts, opportunities" -t complete -o ./src
+
+# Generation types: basic, complete, custom (default)
+objectql ai generate -d "Inventory system" -t complete
+```
+
+**Options:**
+- `-d, --description <text>` - Application description (required)
+- `-o, --output <path>` - Output directory [default: "./src"]
+- `-t, --type <type>` - Generation type: basic, complete, or custom [default: "custom"]
+
+**Generates:**
+- ObjectQL metadata (objects, forms, views, pages, menus, etc.)
+- TypeScript implementations for actions and hooks
+- Jest test files for business logic validation
+
+---
+
+#### Validation
+
+Validate metadata files using AI for compliance and best practices.
+
+```bash
+# Validate all metadata files
+objectql ai validate ./src
+
+# Validate with detailed output
+objectql ai validate ./src -v
+
+# Validate and auto-fix issues
+objectql ai validate ./src --fix
+```
+
+**Options:**
+- `<path>` - Path to metadata directory (required)
+- `--fix` - Automatically fix issues where possible
+- `-v, --verbose` - Show detailed validation output
+
+**Checks:**
+- YAML syntax validation
+- ObjectQL specification compliance
+- Business logic consistency
+- Data model best practices
+- Security and performance analysis
+- Falls back to basic validation if no API key is set
+
+---
+
+#### Chat Assistant
+
+Interactive AI assistant for ObjectQL questions and guidance.
+
+```bash
+# Start chat assistant
+objectql ai chat
+
+# Start with an initial question
+objectql ai chat -p "How do I create a lookup relationship?"
+```
+
+**Options:**
+- `-p, --prompt <text>` - Initial prompt for the AI
+
+---
+
+#### Complete Example Workflow
+
+```bash
+# Set your API key
+export OPENAI_API_KEY=sk-your-api-key-here
+
+# Option 1: Interactive (recommended) - Just type this!
+objectql ai
+
+# Option 2: Quick one-shot generation
+objectql ai generate -d "Project management with tasks and milestones" -t complete
+
+# Validate the generated files
+objectql ai validate ./src -v
+
+# Get help with questions
+objectql ai chat -p "How do I add email notifications?"
+```
+
+---
+
+### Prerequisites
+
+For AI-powered features, set your OpenAI API key:
+
+```bash
+export OPENAI_API_KEY=sk-your-api-key-here
+```
+
+Without an API key, basic validation (YAML syntax) is still available.
+
+---
+
 ### Project Initialization
 
 #### `init`

package/dist/commands/ai.d.ts

@@ -0,0 +1,38 @@
+import { ObjectQLAgent } from '@objectql/core';
+/**
+ * Create an ObjectQL AI agent instance
+ */
+export declare function createAgent(apiKey: string): ObjectQLAgent;
+interface GenerateOptions {
+    description: string;
+    output?: string;
+    type?: 'basic' | 'complete' | 'custom';
+}
+interface ValidateOptions {
+    path: string;
+    fix?: boolean;
+    verbose?: boolean;
+}
+interface ChatOptions {
+    initialPrompt?: string;
+}
+interface ConversationalOptions {
+    output?: string;
+}
+/**
+ * Conversational generation with step-by-step refinement
+ */
+export declare function aiConversational(options: ConversationalOptions): Promise<void>;
+/**
+ * Generate application metadata using AI
+ */
+export declare function aiGenerate(options: GenerateOptions): Promise<void>;
+/**
+ * Validate metadata files using AI
+ */
+export declare function aiValidate(options: ValidateOptions): Promise<void>;
+/**
+ * Interactive AI chat for metadata assistance
+ */
+export declare function aiChat(options: ChatOptions): Promise<void>;
+export {};