Merge pull request #20 from objectql/copilot/add-cli-commands

Author: hotlong

docs/guide/architecture.md

@@ -15,8 +15,7 @@ An ObjectQL application consists of three main layers:
 The project is structured as a monorepo with strict dependency rules to ensure scalability and maintainability.
 
 *   **`@objectql/types`**: The shared contract. Contains all interfaces (`ObjectConfig`, `ObjectQLDriver`). Has **zero dependencies**.
-*   **`@objectql/parser`**: Responsible for parsing YAML/JSON into the internal AST.
-*   **`@objectql/core`**: The main runtime. It depends on `types` and `parser`.
+*   **`@objectql/core`**: The main runtime. It depends on `types`.
 *   **`@objectql/driver-*`**: Database adapters. They implement interfaces from `types` but do **not** depend on `core` (avoiding circular dependencies).
 
 ## Core Concepts

docs/guide/cli.md

@@ -12,13 +12,36 @@ npm install -D @objectql/cli
 
 You can then run it via `npx objectql` or add scripts to your `package.json`.
 
-## 2. Commands
+## 2. Core Commands
 
-### 2.1 `generate` (Type Generation)
+### 2.1 `init` (Create Project)
 
-Scans your `*.object.yml` files and generates TypeScript interfaces. This is crucial for maintaining type safety in your Hooks and Actions.
+Create a new ObjectQL project from a starter template.
+
+```bash
+npx objectql init [options]
+```
+
+**Options:**
+
+| Option | Alias | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `--template <template>` | `-t` | `basic` | Template to use (`basic`, `express-api`, `enterprise`). |
+| `--name <name>` | `-n` | - | Project name. |
+| `--dir <path>` | `-d` | - | Target directory. |
+| `--skip-install` | | `false` | Skip dependency installation. |
+| `--skip-git` | | `false` | Skip git initialization. |
+
+**Example:**
+
+```bash
+npx objectql init -t express-api -n my-app
+```
 
-**Usage:**
+### 2.2 `generate` (Type Generation)
+
+Scans your `*.object.yml` files and generates TypeScript interfaces. This is crucial for maintaining type safety in your Hooks and Actions.
+**Alias**: `g`
 
 ```bash
 npx objectql generate [options]
@@ -28,8 +51,8 @@ npx objectql generate [options]
 
 | Option | Alias | Default | Description |
 | :--- | :--- | :--- | :--- |
-| `--source` | `-s` | `.` | Root directory to search for object files. |
-| `--output` | `-o` | `./src/generated` | Directory where `.ts` files will be generated. |
+| `--source <path>` | `-s` | `.` | Root directory to search for object files. |
+| `--output <path>` | `-o` | `./src/generated` | Directory where `.ts` files will be generated. |
 
 **Example:**
 
@@ -38,54 +61,186 @@ npx objectql generate [options]
 npx objectql generate --source ./src/objects --output ./src/types
 ```
 
-### 2.2 `repl` (Interactive Shell)
+### 2.3 `new` (Scaffold Metadata)
 
-Starts an interactive terminal similar to the MongoDB shell, allowing you to directly query your database using the ObjectQL API.
+Generate a new metadata file (Object, View, Form, etc.) in the project.
+
+```bash
+npx objectql new <type> <name> [options]
+```
+
+**Arguments:**
+*   `<type>`: The type of metadata to generate (e.g., `object`, `view`, `page`).
+*   `<name>`: The name of the file/entity.
+
+**Options:**
+
+| Option | Alias | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `--dir <path>` | `-d` | `.` | Output directory. |
+
+**Example:**
+```bash
+npx objectql new object customer
+```
+
+## 3. Development Tools
+
+### 3.1 `serve` (Dev Server)
+
+Start a standalone development server.
+**Alias**: `s`
+
+```bash
+npx objectql serve [options]
+```
+
+**Options:**
+
+| Option | Alias | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `--port <number>` | `-p` | `3000` | Port to listen on. |
+| `--dir <path>` | `-d` | `.` | Directory containing schema. |
+
+### 3.2 `studio` (Admin UI)
 
-**Prerequisites:**
+Starts the web-based admin studio to browse data and view schema.
+**Alias**: `ui`
+
+```bash
+npx objectql studio [options]
+```
+
+**Options:**
+
+| Option | Alias | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `--port <number>` | `-p` | `3000` | Port to listen on. |
+| `--dir <path>` | `-d` | `.` | Directory containing schema. |
+| `--no-open` | | `false` | Do not open the browser automatically. |
 
-You must have an `objectql.config.ts` or `objectql.config.js` file in your project root that exports your configured `ObjectQL` instance (default export or named export `app`).
+### 3.3 `repl` (Interactive Shell)
 
-**Usage:**
+Starts an interactive terminal similar to the MongoDB shell, allowing you to directly query your database using the ObjectQL API.
+**Alias**: `r`
 
 ```bash
-npx objectql repl
+npx objectql repl [options]
 ```
 
-**Features:**
-*   **Auto-injected Objects:** All your registered objects are available as global variables (e.g., `await tasks.find()`).
-*   **Context:** The `app` instance is available as `app`.
-*   **Sudo Access:** Commands run with system privileges by default in the REPL.
+**Options:**
+
+| Option | Alias | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `--config <path>` | `-c` | - | Path to `objectql.config.ts/js`. |
 
 **Example Session:**
 
 ```javascript
 objectql> await tasks.find({ status: 'todo' })
 [ { id: 1, title: 'Fix bug', status: 'todo' } ]
+```
+
+## 4. Internationalization (i18n)
+
+Tools for managing translations.
+
+### 4.1 `i18n extract`
 
-objectql> await projects.create({ name: 'New API' })
-{ id: 10, name: 'New API', ... }
+Extract translatable strings from metadata files into JSON.
+
+```bash
+npx objectql i18n extract [options]
 ```
 
-### 2.3 `studio` (Admin UI)
+**Options:**
+
+| Option | Alias | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `--source <path>` | `-s` | `.` | Source directory to scan. |
+| `--output <path>` | `-o` | `./src/i18n` | Output directory for translation files. |
+| `--lang <lang>` | `-l` | `en` | Language code. |
 
-Starts the web-based admin studio to browse data and view schema.
-Requires `objectql.config.ts` (or `.js`) to be present in the directory.
+### 4.2 `i18n init`
+
+Initialize i18n structure for a new language.
+
+```bash
+npx objectql i18n init <lang> [options]
+```
+
+**Options:**
+
+| Option | Alias | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `--base-dir <path>` | `-b` | `./src/i18n` | Base i18n directory. |
+
+### 4.3 `i18n validate`
+
+Validate translation completeness against a base language.
+
+```bash
+npx objectql i18n validate <lang> [options]
+```
+
+**Options:**
+
+| Option | Alias | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `--base-dir <path>` | `-b` | `./src/i18n` | Base i18n directory. |
+| `--base-lang <lang>` | | `en` | Base language to compare against. |
+
+## 5. Database Migration
+
+Manage database schema changes.
+
+### 5.1 `migrate`
+
+Run pending database migrations.
+
+```bash
+npx objectql migrate [options]
+```
+
+**Options:**
+
+| Option | Alias | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `--config <path>` | `-c` | - | Path to `objectql.config.ts/js`. |
+| `--dir <path>` | `-d` | `./migrations` | Migrations directory. |
+
+### 5.2 `migrate create`
+
+Create a new migration file.
 
 ```bash
-npx objectql studio
+npx objectql migrate create <name> [options]
 ```
 
-### 2.4 `migration` (Coming Soon)
+**Options:**
+
+| Option | Alias | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `--dir <path>` | `-d` | `./migrations` | Migrations directory. |
+
+### 5.3 `migrate status`
 
-Future versions will include migration commands to sync your YAML schema with the database.
+Show the status of migrations (applied/pending).
 
-*   `migration:create`: Create a new SQL migration file based on schema changes.
-*   `migration:run`: Apply pending migrations to the database.
+```bash
+npx objectql migrate status [options]
+```
+
+**Options:**
+
+| Option | Alias | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `--config <path>` | `-c` | - | Path to `objectql.config.ts/js`. |
+| `--dir <path>` | `-d` | `./migrations` | Migrations directory. |
 
-## 3. Integration with Workflow
+## 6. Integration with Workflow
 
-We recommend adding the generation command to your lifecycle scripts.
+We recommend adding the CLI commands to your lifecycle scripts.
 
 **package.json:**
 
@@ -94,7 +249,8 @@ We recommend adding the generation command to your lifecycle scripts.
   "scripts": {
     "codegen": "objectql generate -s ./src -o ./src/generated",
     "build": "npm run codegen && tsc",
-    "dev": "npm run codegen && ts-node src/index.ts"
+    "dev": "npm run codegen && ts-node src/index.ts",
+    "studio": "objectql studio"
   }
 }
 ```

docs/guide/configuration.md

@@ -24,7 +24,7 @@ The Connection String URI defining the database connection.
 *   `postgres://user:pass@host:5432/db`
 *   `mongodb://host:27017/db`
 
-The engine will automatically load the appropriate driver (`@objectql/driver-knex` or `@objectql/driver-mongo`).
+The engine will automatically load the appropriate driver (`@objectql/driver-sql` or `@objectql/driver-mongo`).
 
 ### `source` (string | string[])
 One or more directory paths (relative or absolute) containing your schema files (`*.object.yml`).

docs/guide/drivers/index.md

@@ -17,7 +17,7 @@ Drivers are instantiated and passed to the `ObjectQL` constructor under the `dri
 
 ```typescript
 import { ObjectQL } from '@objectql/core';
-import { KnexDriver } from '@objectql/driver-knex';
+import { KnexDriver } from '@objectql/driver-sql';
 
 const myDriver = new KnexDriver({ /* options */ });
 

docs/guide/drivers/sql.md

@@ -5,7 +5,7 @@ The SQL driver implementation is based on [Knex.js](https://knexjs.org/), a powe
 ## Installation
 
 ```bash
-npm install @objectql/driver-knex knex pg
+npm install @objectql/driver-sql knex pg
 # Replace 'pg' with 'mysql', 'sqlite3', or 'mssql' depending on your database.
 ```
 
@@ -14,7 +14,7 @@ npm install @objectql/driver-knex knex pg
 The `KnexDriver` constructor accepts the standard [Knex configuration object](https://knexjs.org/guide/#configuration-options).
 
 ```typescript
-import { KnexDriver } from '@objectql/driver-knex';
+import { KnexDriver } from '@objectql/driver-sql';
 
 const driver = new KnexDriver({
   client: 'pg', // 'mysql', 'sqlite3', etc.

docs/guide/getting-started.md

@@ -13,7 +13,7 @@
 Install the core package and a driver (e.g., PostgreSQL or MongoDB).
 
 ```bash
-npm install @objectql/core @objectql/driver-knex knex pg
+npm install @objectql/core @objectql/driver-sql knex pg
 # or
 npm install @objectql/core @objectql/driver-mongo mongodb
 ```

docs/guide/metadata-organization.md

@@ -62,7 +62,7 @@ src/
 
 See the complete working example at:
 ```
-examples/scenarios/enterprise-structure/
+packages/starters/enterprise/
 ```
 
 This demonstrates:
@@ -333,7 +333,7 @@ describe('Account Object', () => {
 
 Explore the full example with 20+ objects:
 ```bash
-cd examples/scenarios/enterprise-structure
+cd packages/starters/enterprise
 pnpm install
 pnpm build
 ```
@@ -362,4 +362,4 @@ The example includes:
 - [Data Modeling Guide](./data-modeling.md)
 - [Plugin Development](./plugins.md)
 - [Logic Hooks](./logic-hooks.md)
-- [Complete Example](../../examples/scenarios/enterprise-structure/)
+- [Complete Example](../../packages/starters/enterprise/)

docs/guide/page-metadata.md

@@ -625,19 +625,19 @@ meta:
 
 ### Complete Dashboard Example
 
-See `examples/starters/basic-script/src/dashboard.page.yml` for a full dashboard implementation.
+See `packages/starters/basic/src/dashboard.page.yml` for a full dashboard implementation.
 
 ### Form Page Example
 
-See `examples/starters/basic-script/src/project_detail.page.yml` for a two-column detail page with forms.
+See `packages/starters/basic/src/project_detail.page.yml` for a two-column detail page with forms.
 
 ### Wizard Example
 
-See `examples/starters/basic-script/src/create_project_wizard.page.yml` for a multi-step wizard.
+See `packages/starters/basic/src/create_project_wizard.page.yml` for a multi-step wizard.
 
 ### Canvas Layout Example
 
-See `examples/starters/basic-script/src/landing.page.yml` for a custom landing page.
+See `packages/starters/basic/src/landing.page.yml` for a custom landing page.
 
 ## Integration with Navigation