feat: Add project and task management modules with comprehensive hooks, permissions, and validation

- Introduced project management features including data structure, hooks for lifecycle events, and validation rules.
- Implemented task management with associated data structure and permissions.
- Added YAML files for initial data, permissions, and validation rules for both projects and tasks.
- Created TypeScript interfaces for projects and tasks to ensure type safety.
- Configured TypeScript settings for the project tracker module.

Author: hotlong

docs/guide/cli.md

@@ -26,7 +26,7 @@ npx objectql init [options]
 
 | Option | Alias | Default | Description |
 | :--- | :--- | :--- | :--- |
-| `--template <template>` | `-t` | `basic` | Template to use (`basic`, `express-api`, `enterprise`). |
+| `--template <template>` | `-t` | `starter` | Template to use (`starter`, `hello-world`). |
 | `--name <name>` | `-n` | - | Project name. |
 | `--dir <path>` | `-d` | - | Target directory. |
 | `--skip-install` | | `false` | Skip dependency installation. |
@@ -35,7 +35,7 @@ npx objectql init [options]
 **Example:**
 
 ```bash
-npx objectql init -t express-api -n my-app
+npx objectql init -t starter -n my-app
 ```
 
 ### 2.2 `generate` (Type Generation)

docs/guide/getting-started.md

@@ -8,23 +8,43 @@
 2.  **Universal Protocol**: The query language is a JSON AST, making it easy for frontends or AI agents to generate queries.
 3.  **Action & Hook System**: Built-in support for "Button Actions" (RPC) and "Triggers" (Hooks), allowing you to model **Behavior** alongside **Data**.
 
-## Quick Start: The "Hello World"
+## Quick Start
 
-You can experience ObjectQL with a single file. No YAML, no complex config.
+The fastest way to get started is using the CLI to scaffold a project.
 
-### 1. Minimal Setup
+### 1. Minimal Setup (Hello World)
 
-Install the core and SQLite driver (for zero-config database).
+Create a single-file project to learn the basics.
 
 ```bash
-npm install @objectql/core @objectql/driver-sql sqlite3
-# or
-pnpm add @objectql/core @objectql/driver-sql sqlite3
+# Initialize a new project
+npx @objectql/cli init --template hello-world --name my-first-app
+
+# Enter directory
+cd my-first-app
+
+# Start the app
+npm start
 ```
 
-### 2. The Universal Script
+This will create an `index.ts` file that defines a schema, initializes an in-memory SQLite database, and runs some queries.
+
+### 2. Standard Setup (Project Tracker)
+
+For building real applications, use the `starter` template. This sets up a proper folder structure with YAML metadata, TypeScript logic hooks, and relationship management.
+
+```bash
+npx @objectql/cli init --template starter --name project-tracker
+```
+
+This structure follows our **Best Practices**:
+*   **`src/objects/*.object.yml`**: Data definitions.
+*   **`src/hooks/*.hook.ts`**: Business logic.
+*   **`src/index.ts`**: Application entry point.
+
+## Manual Setup (The Hard Way)
 
-Create `index.ts`. This script defines the schema, boots the engine, and runs queries in one go.
+If you prefer to set up manually or add ObjectQL to an existing project:
 
 ```typescript
 import { ObjectQL } from '@objectql/core';

packages/tools/cli/package.json

@@ -16,11 +16,17 @@
   ],
   "license": "MIT",
   "main": "dist/index.js",
+  "files": [
+    "dist",
+    "bin",
+    "templates"
+  ],
   "bin": {
     "objectql": "./bin/objectql"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && pnpm run copy-templates",
+    "copy-templates": "rm -rf templates && mkdir -p templates && cp -r ../../../examples/quickstart/hello-world templates/ && cp -r ../../../examples/showcase/project-tracker templates/ && rm -rf templates/*/node_modules templates/*/dist",
     "watch": "tsc -w",
     "test": "jest"
   },

packages/tools/cli/src/commands/init.ts

@@ -15,15 +15,14 @@ interface InitOptions {
 }
 
 const TEMPLATES = {
-    basic: '@objectql/starter-basic',
-    'express-api': '@objectql/starter-express-api',
-    enterprise: '@objectql/starter-enterprise'
+    'hello-world': 'hello-world',
+    'starter': 'project-tracker'
 };
 
 export async function initProject(options: InitOptions) {
     const projectName = options.name || 'my-objectql-project';
     const targetDir = options.dir || path.join(process.cwd(), projectName);
-    const template = (options.template || 'basic') as keyof typeof TEMPLATES;
+    const template = (options.template || 'starter') as keyof typeof TEMPLATES;
 
     if (!TEMPLATES[template]) {
         console.error(chalk.red(`❌ Unknown template: ${template}`));
@@ -45,42 +44,48 @@ export async function initProject(options: InitOptions) {
     fs.mkdirSync(targetDir, { recursive: true });
 
     try {
-        // Copy template files from starters
-        const templatePath = path.join(__dirname, '../../../../starters', template);
-        
-        // Check if we're in the monorepo (for development)
-        if (fs.existsSync(templatePath)) {
-            console.log(chalk.gray('Copying template files...'));
-            await copyDirectory(templatePath, targetDir, ['node_modules', 'dist', '.git']);
-        } else {
-            // Try to use the published package
-            console.log(chalk.gray(`Installing template from npm: ${TEMPLATES[template]}...`));
-            await execAsync(`npm create ${TEMPLATES[template]} ${targetDir}`, { 
-                cwd: process.cwd() 
-            });
+        // Copy embedded template
+        const templateName = TEMPLATES[template];
+        // Must resolve relative to the dist/commands folder structure
+        const sourcePath = path.resolve(__dirname, '../../templates', templateName);
+
+        if (!fs.existsSync(sourcePath)) {
+            // Fallback for development (running directly from src)
+            // If running via ts-node in dev, structure might be different
+             throw new Error(`Template not found at ${sourcePath}. Please check your CLI installation.`);
         }
 
+        console.log(chalk.cyan(`⬇️ Creating project from embedded template...`));
+        await copyDirectory(sourcePath, targetDir, ['node_modules', 'dist', '.git']);
+        console.log(chalk.green('✅ Template created successfully.'));
+
         // Update package.json with project name
         const pkgPath = path.join(targetDir, 'package.json');
         if (fs.existsSync(pkgPath)) {
             const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
             pkg.name = projectName;
             pkg.version = '0.1.0';
-            // Convert workspace dependencies to actual versions for standalone project
-            if (pkg.dependencies) {
-                for (const dep of Object.keys(pkg.dependencies)) {
-                    if (pkg.dependencies[dep] === 'workspace:*') {
-                        pkg.dependencies[dep] = '^1.0.0'; // Use latest published version
-                    }
-                }
-            }
-            if (pkg.devDependencies) {
-                for (const dep of Object.keys(pkg.devDependencies)) {
-                    if (pkg.devDependencies[dep] === 'workspace:*') {
-                        pkg.devDependencies[dep] = '^1.0.0';
+            
+            // Note: Since we are using examples from the monorepo, 
+            // they might have "workspace:*" protocols.
+            // We should replace them with "latest" or a specific version for end users.
+            const replaceWorkspaceVersion = (deps: Record<string, string>) => {
+                for (const dep of Object.keys(deps)) {
+                    if (deps[dep] === 'workspace:*') {
+                        // For public release, this should match the current CLI version or latest
+                        deps[dep] = 'latest'; 
                     }
                 }
-            }
+            };
+
+            if (pkg.dependencies) replaceWorkspaceVersion(pkg.dependencies);
+            if (pkg.devDependencies) replaceWorkspaceVersion(pkg.devDependencies); // Often peerDeps in examples
+
+            // Make public for the user's new project
+            delete pkg.private;
+            // Reset repository field as it will be a new repo
+            delete pkg.repository;
+
             fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2));
         }
 

packages/tools/cli/templates/hello-world/CHANGELOG.md

@@ -0,0 +1,33 @@
+# @example/hello-world
+
+## 1.0.4
+
+### Patch Changes
+
+- Updated dependencies
+  - @objectql/core@1.8.4
+  - @objectql/driver-sql@1.8.4
+
+## 1.0.3
+
+### Patch Changes
+
+- Updated dependencies
+  - @objectql/core@1.8.3
+  - @objectql/driver-sql@1.8.3
+
+## 1.0.2
+
+### Patch Changes
+
+- Updated dependencies
+  - @objectql/core@1.8.2
+  - @objectql/driver-sql@1.8.2
+
+## 1.0.1
+
+### Patch Changes
+
+- Updated dependencies
+  - @objectql/core@1.8.1
+  - @objectql/driver-sql@1.8.1

packages/tools/cli/templates/hello-world/README.md

@@ -0,0 +1,29 @@
+# Hello ObjectQL
+
+This is the simplest possible example of **ObjectQL**.
+
+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.
+
+## How to Run
+
+Since you are in the monorepo, simply run:
+
+```bash
+# Install dependencies (if not already done at root)
+pnpm install
+
+# Run the script
+cd examples/starters/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.

packages/tools/cli/templates/hello-world/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@objectql/example-hello-world",
+  "version": "1.0.4",
+  "private": true,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/objectql/objectql.git",
+    "directory": "examples/quickstart/hello-world"
+  },
+  "description": "Zero-config ObjectQL starter",
+  "scripts": {
+    "start": "ts-node src/index.ts"
+  },
+  "dependencies": {
+    "@objectql/core": "workspace:*",
+    "@objectql/driver-sql": "workspace:*",
+    "sqlite3": "^5.1.7"
+  },
+  "devDependencies": {
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.3",
+    "@types/node": "^20.11.24"
+  }
+}

packages/tools/cli/templates/hello-world/src/index.ts

@@ -0,0 +1,58 @@
+import { ObjectQL } from '@objectql/core';
+import { SqlDriver } from '@objectql/driver-sql';
+
+async function main() {
+  console.log("🚀 Starting ObjectQL Hello World...");
+
+  // 1. Initialize Driver
+  const driver = new SqlDriver({
+    client: 'sqlite3',
+    connection: { filename: ':memory:' }, 
+    useNullAsDefault: true
+  });
+
+  // 2. Initialize Engine (Pass driver in config)
+  const app = new ObjectQL({
+    datasources: {
+        default: driver
+    }
+  });
+  
+  // 3. Define Metadata Inline
+  app.registerObject({
+    name: 'deal',
+    fields: {
+      title: { type: 'text', required: true },
+      amount: { type: 'currency' },
+      stage: { 
+        type: 'select', 
+        options: [
+            { label: 'New', value: 'new' },
+            { label: 'Negotiation', value: 'negotiation' },
+            { label: 'Closed', value: 'closed' }
+        ],
+        defaultValue: 'new'
+      }
+    }
+  });
+
+  await app.init(); // Boot the engine
+
+  // 4. Run Business Logic
+  const ctx = app.createContext({ isSystem: true });
+  const repo = ctx.object('deal');
+  
+  console.log("Creating a new Deal...");
+  await repo.create({ 
+    title: 'Enterprise Contract', 
+    amount: 50000, 
+    stage: 'new' 
+  });
+  
+  const results = await repo.find({});
+  console.log('✅ Deals found in database:', results); 
+}
+
+if (require.main === module) {
+    main().catch(console.error);
+}

packages/tools/cli/templates/hello-world/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "module": "CommonJS",
+    "moduleResolution": "node"
+  },
+  "include": ["src/**/*"]
+}