@objectql/cli 1.8.2 → 1.8.4

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @objectql/cli
 
+## 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
+  - @objectql/server@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/server@1.8.3
+  - @objectql/types@1.8.3
+  - @objectql/platform-node@1.8.3
+
 ## 1.8.2
 
 ### Patch Changes

package/README.md

@@ -356,12 +356,241 @@ objectql migrate status --config ./config/objectql.config.ts
 - `-c, --config <path>` - Path to objectql.config.ts/js
 - `-d, --dir <path>` - Migrations directory [default: "./migrations"]
 
+#### `sync`
+
+Introspect an existing SQL database and generate ObjectQL `.object.yml` files from the database schema. This is useful for:
+- Connecting to an existing/legacy database
+- Reverse-engineering database schema to ObjectQL metadata
+- Bootstrapping a new ObjectQL project from an existing database
+
+```bash
+# Sync all tables from the database
+objectql sync
+
+# Sync specific tables only
+objectql sync --tables users posts comments
+
+# Custom output directory
+objectql sync --output ./src/metadata/objects
+
+# Overwrite existing files
+objectql sync --force
+
+# With custom config file
+objectql sync --config ./config/objectql.config.ts
+```
+
+**Options:**
+- `-c, --config <path>` - Path to objectql.config.ts/js
+- `-o, --output <path>` - Output directory for .object.yml files [default: "./src/objects"]
+- `-t, --tables <tables...>` - Specific tables to sync (default: all tables)
+- `-f, --force` - Overwrite existing .object.yml files
+
+**Features:**
+- Automatically detects table structure (columns, data types, constraints)
+- Maps SQL types to appropriate ObjectQL field types
+- Identifies foreign keys and converts them to `lookup` relationships
+- Generates human-readable labels from table/column names
+- Preserves field constraints (required, unique, maxLength)
+- Skips system fields (id, created_at, updated_at) as they're automatic in ObjectQL
+
+**Example:**
+
+Given a database with this table structure:
+```sql
+CREATE TABLE users (
+    id VARCHAR PRIMARY KEY,
+    username VARCHAR UNIQUE NOT NULL,
+    email VARCHAR NOT NULL,
+    is_active BOOLEAN DEFAULT true,
+    created_at TIMESTAMP,
+    updated_at TIMESTAMP
+);
+```
+
+Running `objectql sync` generates:
+```yaml
+# users.object.yml
+name: users
+label: Users
+fields:
+  username:
+    type: text
+    label: Username
+    required: true
+    unique: true
+  email:
+    type: text
+    label: Email
+    required: true
+  is_active:
+    type: boolean
+    label: Is Active
+    defaultValue: true
+```
+
 ---
 
 ### Development Tools
 
+#### `dev` (alias: `d`)
+
+Start development server with hot reload support. This is the recommended command for local development.
+
+```bash
+# Start development server (port 3000)
+objectql dev
+
+# Specify options
+objectql dev --dir ./src --port 8080
+
+# Disable file watching
+objectql dev --no-watch
+```
+
+The development server provides:
+- **Swagger UI**: `http://localhost:<port>/swagger` - Interactive API documentation
+- **API Endpoint**: `http://localhost:<port>/` - Main API endpoint
+- **OpenAPI Spec**: `http://localhost:<port>/openapi.json` - Machine-readable API spec
+
+**Options:**
+- `-p, --port <number>` - Port to listen on [default: "3000"]
+- `-d, --dir <path>` - Directory containing schema [default: "."]
+- `--no-watch` - Disable file watching (future feature)
+
+#### `start`
+
+Start production server. Loads configuration from `objectql.config.ts/js` if available.
+
+```bash
+# Start production server
+objectql start
+
+# Specify options
+objectql start --port 8080 --dir ./dist
+
+# Use custom config file
+objectql start --config ./config/production.config.ts
+```
+
+**Options:**
+- `-p, --port <number>` - Port to listen on [default: "3000"]
+- `-d, --dir <path>` - Directory containing schema [default: "."]
+- `-c, --config <path>` - Path to objectql.config.ts/js
+
+**Environment Variables:**
+- `DATABASE_FILE` - Path to SQLite database file (default: "./objectql.db")
+
+#### `build` (alias: `b`)
+
+Build project and prepare for production deployment. Validates metadata, generates TypeScript types, and copies files to dist folder.
+
+```bash
+# Build project
+objectql build
+
+# Build with custom output directory
+objectql build --output ./build
+
+# Build without type generation
+objectql build --no-types
+
+# Build without validation
+objectql build --no-validate
+```
+
+**Options:**
+- `-d, --dir <path>` - Source directory [default: "."]
+- `-o, --output <path>` - Output directory [default: "./dist"]
+- `--no-types` - Skip TypeScript type generation
+- `--no-validate` - Skip metadata validation
+
+**Build Steps:**
+1. Validates all metadata files
+2. Generates TypeScript type definitions (if enabled)
+3. Copies all metadata files (.yml) to dist folder
+
+#### `test` (alias: `t`)
+
+Run tests for the ObjectQL project. Automatically detects and runs Jest tests if configured.
+
+```bash
+# Run all tests
+objectql test
+
+# Run tests in watch mode
+objectql test --watch
+
+# Run tests with coverage report
+objectql test --coverage
+
+# Specify project directory
+objectql test --dir ./src
+```
+
+**Options:**
+- `-d, --dir <path>` - Project directory [default: "."]
+- `-w, --watch` - Watch mode (re-run tests on file changes)
+- `--coverage` - Generate coverage report
+
+**Requirements:**
+- Jest must be installed and configured in package.json
+- Falls back to `npm test` if Jest is not detected
+
+#### `lint` (alias: `l`)
+
+Validate metadata files for correctness and best practices.
+
+```bash
+# Lint all metadata files
+objectql lint
+
+# Lint specific directory
+objectql lint --dir ./src/objects
+
+# Auto-fix issues (future feature)
+objectql lint --fix
+```
+
+**Options:**
+- `-d, --dir <path>` - Directory to lint [default: "."]
+- `--fix` - Automatically fix issues (future feature)
+
+**Validation Rules:**
+- Object and field names must be lowercase with underscores
+- All objects should have labels
+- All fields should have labels
+- No empty objects (objects must have at least one field)
+
+#### `format` (alias: `fmt`)
+
+Format metadata files using Prettier for consistent styling.
+
+```bash
+# Format all YAML files
+objectql format
+
+# Format specific directory
+objectql format --dir ./src
+
+# Check formatting without modifying files
+objectql format --check
+```
+
+**Options:**
+- `-d, --dir <path>` - Directory to format [default: "."]
+- `--check` - Check if files are formatted without modifying them
+
+**Formatting Rules:**
+- Uses Prettier with YAML parser
+- Print width: 80 characters
+- Tab width: 2 spaces
+- Single quotes for strings
+
 #### `serve` (alias: `s`)
 
+*Note: This is an alias for the `dev` command, kept for backwards compatibility. Use `objectql dev` for new projects.*
+
 Start a lightweight development server with an in-memory database. Perfect for rapid prototyping without setting up a backend project.
 
 ```bash

package/USAGE_EXAMPLES.md

@@ -517,6 +517,153 @@ export async function up(app: ObjectQL) {
 }
 ```
 
+### Syncing from Existing Database
+
+The `sync` command introspects an existing SQL database and generates ObjectQL `.object.yml` files.
+
+#### Basic Sync
+
+```bash
+# Sync all tables from the database
+objectql sync
+
+# Output: src/objects/users.object.yml, src/objects/posts.object.yml, etc.
+```
+
+#### Selective Table Sync
+
+```bash
+# Sync only specific tables
+objectql sync --tables users posts comments
+
+# Custom output directory
+objectql sync --output ./src/metadata/objects
+```
+
+#### Overwriting Existing Files
+
+```bash
+# Force overwrite of existing .object.yml files
+objectql sync --force
+```
+
+#### Example Workflow: Connecting to Legacy Database
+
+```bash
+# 1. Create config file pointing to existing database
+cat > objectql.config.ts << 'EOF'
+import { ObjectQL } from '@objectql/core';
+import { SqlDriver } from '@objectql/driver-sql';
+
+const driver = new SqlDriver({
+    client: 'postgresql',
+    connection: {
+        host: 'localhost',
+        database: 'legacy_db',
+        user: 'postgres',
+        password: 'password'
+    }
+});
+
+export default new ObjectQL({
+    datasources: { default: driver }
+});
+EOF
+
+# 2. Introspect and generate object definitions
+objectql sync --output ./src/objects
+
+# 3. Review generated files
+ls -la ./src/objects/
+
+# Output:
+# users.object.yml
+# products.object.yml
+# orders.object.yml
+# order_items.object.yml
+
+# 4. Inspect a generated file
+cat ./src/objects/users.object.yml
+```
+
+**Generated Output Example:**
+
+```yaml
+# users.object.yml
+name: users
+label: Users
+fields:
+  username:
+    type: text
+    label: Username
+    required: true
+    unique: true
+  email:
+    type: text
+    label: Email
+    required: true
+  first_name:
+    type: text
+    label: First Name
+  last_name:
+    type: text
+    label: Last Name
+  is_active:
+    type: boolean
+    label: Is Active
+    defaultValue: true
+  role_id:
+    type: lookup
+    label: Role Id
+    reference_to: roles
+```
+
+**Type Mapping:**
+
+The sync command automatically maps SQL types to ObjectQL field types:
+
+| SQL Type | ObjectQL Type |
+|----------|---------------|
+| INT, INTEGER, BIGINT, SERIAL | number |
+| FLOAT, DOUBLE, DECIMAL, NUMERIC | number |
+| BOOLEAN, BIT | boolean |
+| VARCHAR, CHAR | text |
+| TEXT, CLOB, LONGTEXT | textarea |
+| TIMESTAMP, DATETIME | datetime |
+| DATE | date |
+| TIME | time |
+| JSON, JSONB | object |
+| BLOB, BINARY, BYTEA | file |
+
+**Foreign Key Detection:**
+
+Foreign keys are automatically detected and converted to `lookup` fields:
+
+```sql
+-- Database Schema
+CREATE TABLE posts (
+    id VARCHAR PRIMARY KEY,
+    title VARCHAR NOT NULL,
+    author_id VARCHAR REFERENCES users(id),
+    ...
+);
+```
+
+```yaml
+# Generated posts.object.yml
+name: posts
+label: Posts
+fields:
+  title:
+    type: text
+    label: Title
+    required: true
+  author_id:
+    type: lookup
+    label: Author Id
+    reference_to: users
+```
+
 ---
 
 ## Development Tools