@objectql/cli 1.7.1 → 1.7.3

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,29 @@
 # @objectql/cli
 
+## 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
+
+- Release patch version 1.7.2
+- Updated dependencies
+  - @objectql/driver-sql@1.7.2
+  - @objectql/core@1.7.2
+  - @objectql/platform-node@1.7.2
+  - @objectql/types@1.7.2
+  - @objectql/server@1.7.2
+
 ## 1.7.1
 
 ### Patch Changes

package/LICENSE

@@ -1,21 +1,118 @@
-MIT License
-
-Copyright (c) 2026 ObjectQL Contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+# PolyForm Shield License 1.0.0
+
+<https://polyformproject.org/licenses/shield/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose. However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software. Your license
+to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software. For example:
+
+> Required Notice: Copyright ObjectQL Contributors (https://github.com/objectql)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else. These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice. Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization. **Control**
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise. Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.
+
+**Permitted purpose** means any purpose other than competing
+with the licensor or any product the licensor or its affiliates
+provides using the software.
+
+---
+
+Required Notice: Copyright (c) 2026 ObjectQL Contributors (https://github.com/objectql)

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 {};