@objectql/create 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+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
+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.

package/README.md

@@ -0,0 +1,28 @@
+# @objectql/create
+
+The easiest way to get started with ObjectQL.
+
+## Usage
+
+```bash
+npm create @objectql@latest
+```
+
+Follow the prompts to create your new ObjectQL application.
+
+## Arguments
+
+You can also pass arguments directly:
+
+```bash
+npm create @objectql@latest <project-name> --template <template-name>
+```
+
+- `<project-name>`: Name of the project directory.
+- `--template`: Template to use (e.g. `hello-world` or `showcase`).
+
+## Features
+
+- **Embedded Templates**: No internet connection required to fetch templates.
+- **Auto-Cleanup**: Automatically cleans up `package.json` configurations (strips `private: true`, resolves workspace versions).
+- **Interactive**: Uses `enquirer` for a smooth interactive experience if no arguments are provided.

package/dist/bin.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs-extra"));
+const chalk_1 = __importDefault(require("chalk"));
+const enquirer_1 = __importDefault(require("enquirer"));
+const { prompt } = enquirer_1.default;
+const program = new commander_1.Command();
+program
+    .name('create-objectql')
+    .description('Scaffold a new ObjectQL project')
+    .argument('[directory]', 'Directory to create the project in')
+    .option('-t, --template <name>', 'Template to use (hello-world, starter, enterprise)')
+    .action(async (directory, options) => {
+    console.log(chalk_1.default.bold.blue('⚡ ObjectStack AI - Project Scaffolder'));
+    // 1. Resolve Target Directory
+    let targetDir = directory;
+    if (!targetDir) {
+        const response = await prompt({
+            type: 'input',
+            name: 'dir',
+            message: 'Where should we create the project?',
+            initial: 'my-app'
+        });
+        targetDir = response.dir;
+    }
+    const root = path.resolve(process.cwd(), targetDir);
+    // 2. Resolve Template Source (Embedded)
+    // The templates are located in ../templates relative to the dist/bin.js file
+    // dist/bin.js -> ../templates -> package-root/templates
+    let templateName = options.template;
+    if (!templateName) {
+        const response = await prompt({
+            type: 'select',
+            name: 'template',
+            message: 'Select a starter template:',
+            choices: [
+                { message: 'Standard Project (Recommended)', name: 'starter' },
+                { message: 'Enterprise ERP System', name: 'enterprise' },
+                { message: 'Minimal (Hello World)', name: 'hello-world' }
+            ]
+        });
+        templateName = response.template;
+    }
+    // Legacy mapping or aliasing if needed
+    if (templateName === 'project-tracker')
+        templateName = 'starter';
+    const templatePath = path.resolve(__dirname, '../templates', templateName);
+    if (!fs.existsSync(templatePath)) {
+        console.error(chalk_1.default.red(`❌ Template '${templateName}' not found in package.`));
+        console.error(chalk_1.default.gray(`Path looked for: ${templatePath}`));
+        process.exit(1);
+    }
+    // 3. Copy Files
+    console.log(`\nCreating project in ${chalk_1.default.green(root)}...`);
+    await fs.ensureDir(root);
+    await fs.copy(templatePath, root);
+    // 4. Update package.json (De-monorepo)
+    const pkgPath = path.join(root, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+        const pkg = await fs.readJson(pkgPath);
+        delete pkg.private;
+        delete pkg.repository;
+        const updateDeps = (deps) => {
+            if (!deps)
+                return;
+            for (const key in deps) {
+                if (deps[key] === 'workspace:*') {
+                    deps[key] = 'latest';
+                }
+            }
+        };
+        updateDeps(pkg.dependencies);
+        updateDeps(pkg.devDependencies);
+        await fs.writeJson(pkgPath, pkg, { spaces: 2 });
+    }
+    // 5. Initialize Git
+    try {
+        await fs.writeFile(path.join(root, '.gitignore'), `node_modules/\ndist/\n*.log\n.DS_Store\n*.sqlite3\n.env\n.env.local\n`);
+    }
+    catch { }
+    console.log(chalk_1.default.green('\n✅ Done! Now run:\n'));
+    console.log(chalk_1.default.cyan(`  cd ${targetDir}`));
+    console.log(chalk_1.default.cyan(`  npm install`));
+    console.log(chalk_1.default.cyan(`  npm start`));
+});
+program.parse(process.argv);

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@objectql/create",
+  "version": "1.0.0",
+  "description": "Create ObjectQL apps with one command",
+  "bin": {
+    "create-objectql": "./dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "commander": "^11.0.0",
+    "enquirer": "^2.4.1",
+    "fs-extra": "^11.3.3"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "scripts": {
+    "build": "tsc && node scripts/copy-templates.js",
+    "copy-templates": "node scripts/copy-templates.js"
+  }
+}

package/templates/enterprise/CHANGELOG.md

@@ -0,0 +1,140 @@
+# @objectql/starter-enterprise
+
+## 1.8.4
+
+### Patch Changes
+
+- Release version 1.8.4 with latest improvements and bug fixes
+- Updated dependencies
+  - @objectql/types@1.8.4
+  - @objectql/core@1.8.4
+  - @objectql/platform-node@1.8.4
+  - @objectql/driver-sql@1.8.4
+
+## 1.8.3
+
+### Patch Changes
+
+- Release patch version 1.8.3
+
+  Small version update with latest improvements and bug fixes.
+
+- Updated dependencies
+  - @objectql/core@1.8.3
+  - @objectql/driver-sql@1.8.3
+  - @objectql/types@1.8.3
+  - @objectql/platform-node@1.8.3
+
+## 1.8.2
+
+### Patch Changes
+
+- Patch release v1.8.2 - Small version update with latest improvements
+- Updated dependencies
+  - @objectql/core@1.8.2
+  - @objectql/driver-sql@1.8.2
+  - @objectql/types@1.8.2
+  - @objectql/platform-node@1.8.2
+
+## 1.8.1
+
+### Patch Changes
+
+- Patch release with documentation updates and bug fixes
+- Updated dependencies
+  - @objectql/core@1.8.1
+  - @objectql/driver-sql@1.8.1
+  - @objectql/types@1.8.1
+  - @objectql/platform-node@1.8.1
+
+## 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/types@2.0.0
+  - @objectql/platform-node@2.0.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/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
+
+## 1.7.1
+
+### Patch Changes
+
+- Release small version update with latest improvements
+- Updated dependencies
+  - @objectql/core@1.7.1
+  - @objectql/driver-sql@1.7.1
+  - @objectql/types@1.7.1
+  - @objectql/platform-node@1.7.1
+
+## 1.7.0
+
+### Minor Changes
+
+- Release version 1.7.0 with improvements and bug fixes:
+  - Updated default port for ObjectQL Studio to 5555
+  - Improved port listening logic in Studio
+  - Enhanced stability and performance
+
+## 1.6.1
+
+### Patch Changes
+
+- Updated dependencies
+  - @objectql/core@1.6.1
+  - @objectql/platform-node@1.6.1
+  - @objectql/driver-sql@1.6.1
+  - @objectql/types@1.6.1
+
+## 1.8.0
+
+### Patch Changes
+
+- Updated dependencies
+  - @objectql/core@1.6.0
+  - @objectql/driver-sql@1.6.0
+  - @objectql/types@1.6.0
+  - @objectql/platform-node@1.6.0
+
+## 1.0.0
+
+### Added
+
+- Initial release with enterprise-scale metadata organization example
+- Core module with user, organization, and attachment objects
+- CRM module with account, contact, opportunity, and lead objects
+- HR module with employee, department, position, and timesheet objects
+- Finance module with invoice, payment, expense, and budget objects
+- Project module with project, task, milestone, and timesheet entry objects
+- Extension pattern demonstration with user extensions
+- Comprehensive documentation for each module
+- Shared utilities, constants, and validators
+- Module index files for clean exports
+- README with best practices and architecture guidance

package/templates/enterprise/README.md

@@ -0,0 +1,352 @@
+# Enterprise-Scale Metadata Organization
+
+This example demonstrates **best practices for organizing metadata** in large-scale ObjectQL projects, suitable for enterprise applications with hundreds of objects and complex business domains.
+
+## 📋 Problem Statement
+
+When building large applications, poor metadata organization leads to:
+- **Difficulty finding objects** - scattered files with no clear structure
+- **Merge conflicts** - multiple teams editing the same files
+- **Unclear ownership** - no way to know which team owns which domain
+- **Deployment risks** - can't deploy modules independently
+- **Maintenance burden** - hard to understand relationships between objects
+
+## 🎯 Solution: Domain-Driven Structure
+
+This example shows a **modular, domain-based** organization pattern that scales to enterprise needs.
+
+```
+src/
+├── core/                      # Shared/Foundation Layer
+│   ├── objects/              # Base objects used across domains
+│   │   ├── user.object.yml
+│   │   ├── organization.object.yml
+│   │   └── attachment.object.yml
+│   ├── i18n/
+│   │   ├── en/
+│   │   └── zh-CN/
+│   └── index.ts
+│
+├── modules/                   # Business Domain Modules
+│   ├── crm/                  # Customer Relationship Module
+│   │   ├── objects/
+│   │   │   ├── crm_account.object.yml
+│   │   │   ├── crm_contact.object.yml
+│   │   │   ├── crm_opportunity.object.yml
+│   │   │   └── crm_lead.object.yml
+│   │   ├── actions/
+│   │   │   └── convert-lead.action.ts
+│   │   ├── hooks/
+│   │   │   └── opportunity.hooks.ts
+│   │   ├── i18n/
+│   │   │   ├── en/
+│   │   │   └── zh-CN/
+│   │   ├── README.md
+│   │   └── index.ts
+│   │
+│   ├── hr/                   # Human Resources Module
+│   │   ├── objects/
+│   │   │   ├── hr_employee.object.yml
+│   │   │   ├── hr_department.object.yml
+│   │   │   ├── hr_position.object.yml
+│   │   │   └── hr_timesheet.object.yml
+│   │   ├── actions/
+│   │   ├── hooks/
+│   │   ├── i18n/
+│   │   ├── README.md
+│   │   └── index.ts
+│   │
+│   ├── finance/              # Finance & Accounting Module
+│   │   ├── objects/
+│   │   │   ├── finance_invoice.object.yml
+│   │   │   ├── finance_payment.object.yml
+│   │   │   ├── finance_expense.object.yml
+│   │   │   └── finance_budget.object.yml
+│   │   ├── actions/
+│   │   ├── hooks/
+│   │   ├── i18n/
+│   │   ├── README.md
+│   │   └── index.ts
+│   │
+│   └── project/              # Project Management Module
+│       ├── objects/
+│       │   ├── project_project.object.yml
+│       │   ├── project_task.object.yml
+│       │   ├── project_milestone.object.yml
+│       │   └── project_timesheet_entry.object.yml
+│       ├── actions/
+│       ├── hooks/
+│       ├── i18n/
+│       ├── README.md
+│       └── index.ts
+│
+├── extensions/               # Custom Extensions/Overrides
+│   ├── user.extension.object.yml
+│   └── README.md
+│
+├── shared/                   # Shared Utilities
+│   ├── constants.ts
+│   ├── validators.ts
+│   └── utils.ts
+│
+└── index.ts                  # Application Entry Point
+```
+
+## 🏗️ Architecture Principles
+
+### 1. **Separation of Concerns**
+Each module is self-contained with its own:
+- Object definitions (`.object.yml`)
+- Business logic (actions & hooks)
+- Translations (i18n)
+- Documentation
+
+### 2. **Clear Dependencies**
+```
+Application Layer (modules/*)
+        ↓
+  Foundation Layer (core/*)
+        ↓
+   External Plugins
+```
+
+### 3. **Team Ownership**
+Each module can be owned by a different team:
+- `modules/crm/` → Sales Team
+- `modules/hr/` → HR Team
+- `modules/finance/` → Finance Team
+
+### 4. **Independent Deployment**
+Modules can be:
+- Developed in parallel
+- Tested independently
+- Deployed as feature flags
+- Extracted to separate packages
+
+## 📦 Module Structure
+
+Each module follows this pattern:
+
+```
+modules/[domain]/
+├── objects/              # Domain object definitions
+├── actions/              # Custom actions (*.action.ts)
+├── hooks/                # Lifecycle hooks (*.hooks.ts)
+├── i18n/                 # Module-specific translations
+│   ├── en/
+│   └── zh-CN/
+├── README.md             # Module documentation
+└── index.ts              # Module exports
+```
+
+## 🔗 Object Naming Conventions
+
+### Prefixing Strategy
+For large projects, consider prefixing object names:
+
+```yaml
+# ❌ Bad: Name collision risk
+name: task
+
+# ✅ Good: Clear module ownership
+name: project_task
+```
+
+**When to prefix:**
+- ✅ When multiple modules might have similar concepts
+- ✅ In multi-tenant or plugin architectures
+- ❌ When it's clearly a core shared object (e.g., `user`, `organization`)
+
+### File Naming
+```
+[object_name].object.yml     # Object definition
+[object_name].action.ts      # Actions for this object
+[object_name].hooks.ts       # Hooks for this object
+[object_name].data.yml       # Seed data (optional)
+```
+
+## 🌐 Internationalization at Scale
+
+### Three-Layer Strategy
+
+1. **Core Layer** (`core/i18n/`)
+   - Shared objects (user, organization)
+   - Common UI labels
+   
+2. **Module Layer** (`modules/[domain]/i18n/`)
+   - Domain-specific objects
+   - Business terminology
+
+3. **Extension Layer** (`extensions/i18n/`)
+   - Customer-specific customizations
+   - Regional variants
+
+### Example Structure
+```
+core/i18n/
+  en/
+    user.json
+    organization.json
+  zh-CN/
+    user.json
+    organization.json
+
+modules/crm/i18n/
+  en/
+    account.json
+    opportunity.json
+  zh-CN/
+    account.json
+    opportunity.json
+```
+
+## 🔐 Index & Performance Strategy
+
+### Field-Level Indexes (Simple)
+For single-column lookups:
+```yaml
+fields:
+  email:
+    type: text
+    unique: true    # Creates unique index
+  status:
+    type: select
+    index: true     # Creates regular index
+```
+
+### Composite Indexes (Advanced)
+Define at object root for multi-column queries:
+```yaml
+indexes:
+  # For query: WHERE status = 'open' ORDER BY created_at DESC
+  status_created_idx:
+    fields: [status, created_at]
+  
+  # For unique constraint: UNIQUE(company_id, email)
+  company_email_unique:
+    fields: [company_id, email]
+    unique: true
+```
+
+### Index Strategy by Module
+
+**High-Traffic Modules** (CRM, Finance):
+- Add indexes on every filter field
+- Use composite indexes for common query patterns
+- Monitor query performance regularly
+
+**Low-Traffic Modules** (HR, Admin):
+- Basic indexes on primary lookup fields
+- Add more as needed based on usage
+
+## 🧩 Extension Pattern
+
+Use extensions to customize objects without modifying core definitions:
+
+**Core Definition** (`core/objects/user.object.yml`):
+```yaml
+name: user
+fields:
+  name: { type: text }
+  email: { type: text }
+```
+
+**Extension** (`extensions/user.extension.object.yml`):
+```yaml
+name: user  # Same name triggers merge
+fields:
+  # Add custom field
+  employee_id:
+    type: text
+    label: Employee ID
+  
+  # Override existing field
+  email:
+    required: true
+    unique: true
+```
+
+## 🧪 Testing Strategy
+
+### Unit Tests
+Test individual object schemas:
+```typescript
+// modules/crm/objects/__tests__/account.test.ts
+describe('Account Object', () => {
+  it('should have required fields', () => {
+    const account = loadObject('account');
+    expect(account.fields.name.required).toBe(true);
+  });
+});
+```
+
+### Integration Tests
+Test module interactions:
+```typescript
+// modules/crm/__tests__/integration.test.ts
+describe('CRM Module', () => {
+  it('should convert lead to opportunity', async () => {
+    // Test cross-object logic
+  });
+});
+```
+
+## 📊 Real-World Size Reference
+
+| Project Size | Objects | Modules | Teams | Structure |
+|--------------|---------|---------|-------|-----------|
+| **Small** (Startup) | 10-30 | 1-2 | 1 | Flat `/objects/` |
+| **Medium** (Scale-up) | 30-100 | 3-5 | 2-3 | `/modules/` by domain |
+| **Large** (Enterprise) | 100-500 | 8-15 | 5-10 | `/modules/` + `/plugins/` |
+| **Very Large** (Platform) | 500+ | 15+ | 10+ | Monorepo with packages |
+
+## 🚀 Migration Path
+
+### From Flat to Modular
+
+1. **Analyze** - Group objects by business domain
+2. **Create** - Create module directories
+3. **Move** - Relocate objects to appropriate modules
+4. **Test** - Verify imports and references still work
+5. **Document** - Update README files
+
+### Gradual Approach
+You don't have to reorganize everything at once:
+```
+src/
+├── objects/          # Legacy flat structure (deprecated)
+├── modules/          # New modular structure
+│   └── crm/          # Start with one module
+└── index.ts          # Loads from both
+```
+
+## 💡 Pro Tips
+
+1. **Start Simple** - Don't over-engineer for 10 objects. Use modules when you hit 30-50 objects.
+
+2. **Document Boundaries** - Each module README should explain:
+   - What business domain it covers
+   - Key objects and relationships
+   - Team ownership
+   - Dependencies on other modules
+
+3. **Avoid Circular Dependencies** - Use shared objects in `core/` to break cycles.
+
+4. **Version Control** - Use `.gitignore` to exclude generated files:
+   ```
+   dist/
+   *.generated.ts
+   node_modules/
+   ```
+
+5. **Code Generation** - Run `objectql generate` to create TypeScript types for each module separately.
+
+## 📚 See Also
+
+- [Data Modeling Guide](../../../docs/guide/data-modeling.md)
+- [Plugin Development](../../../docs/guide/plugins.md)
+- [ObjectQL Architecture](../../../docs/guide/architecture.md)
+
+## 🤝 Contributing
+
+This is a living example. If you have suggestions for enterprise-scale patterns, please open an issue or PR!