@famgia/omnify-cli 0.0.3 → 0.0.5

package/README.md

@@ -5,67 +5,305 @@ CLI tool for the Omnify schema system. Generate Laravel migrations and TypeScrip
 ## Installation
 
 ```bash
+# Global installation
 npm install -g @famgia/omnify-cli
-# or
-npx @famgia/omnify-cli
+
+# Or use with npx
+npx @famgia/omnify-cli <command>
+
+# Or install in project
+npm install @famgia/omnify-cli @famgia/omnify-laravel
+```
+
+## Quick Start
+
+```bash
+# 1. Initialize project
+npx omnify init
+
+# 2. Edit omnify.config.ts to set your database URL
+
+# 3. Define schemas in schemas/ directory
+
+# 4. Validate and generate
+npx omnify validate
+npx omnify generate
 ```
 
 ## Commands
 
-### Initialize project
+### `omnify init`
+
+Initialize a new Omnify project.
 
 ```bash
-omnify init
+omnify init [options]
+
+Options:
+  -f, --force    Overwrite existing files
 ```
 
-Creates `omnify.config.ts` and sample schema files.
+Creates:
+- `omnify.config.ts` - Configuration file with plugin setup
+- `schemas/User.yaml` - Example schema file
 
-### Validate schemas
+After initialization, you'll see step-by-step setup instructions.
+
+### `omnify validate`
+
+Validate all schema files for errors.
 
 ```bash
-omnify validate
+omnify validate [options]
+
+Options:
+  -v, --verbose  Show detailed output
+```
+
+Example output:
 ```
+Validating Schemas
 
-### Generate migrations
+Loading schemas from ./schemas
+Found 3 schema(s)
+Validating schemas...
+
+All schemas are valid!
+```
+
+### `omnify diff`
+
+Show pending schema changes without generating files.
 
 ```bash
-omnify generate
+omnify diff [options]
+
+Options:
+  -v, --verbose  Show detailed output
 ```
 
-Generates:
-- Laravel PHP migrations
-- TypeScript type definitions
-- Atlas HCL schemas
+Uses Atlas to compare your schemas against the lock file and shows what migrations would be generated.
+
+### `omnify generate`
 
-### Show diff
+Generate Laravel migrations and TypeScript types.
 
 ```bash
-omnify diff
+omnify generate [options]
+
+Options:
+  -v, --verbose         Show detailed output
+  --migrations-only     Only generate Laravel migrations
+  --types-only          Only generate TypeScript types
+  -f, --force           Generate even if no changes detected
 ```
 
-Shows pending schema changes without generating files.
+Example:
+```bash
+# Generate everything
+omnify generate
+
+# Only migrations
+omnify generate --migrations-only
+
+# Only TypeScript types
+omnify generate --types-only
+
+# Force regeneration
+omnify generate --force
+
+# Verbose output
+omnify generate -v
+```
 
 ## Configuration
 
+### Basic Configuration
+
 Create `omnify.config.ts`:
 
 ```typescript
-import { defineConfig } from '@famgia/omnify-cli';
+import { defineConfig } from '@famgia/omnify';
+import laravel from '@famgia/omnify-laravel/plugin';
 
 export default defineConfig({
-  schemaDir: './schemas',
-  outputDir: './generated',
-  migrations: {
-    outputDir: './database/migrations',
+  schemasDir: './schemas',
+  lockFilePath: './omnify.lock',
+
+  database: {
+    driver: 'mysql',
+    devUrl: 'mysql://root:password@localhost:3306/omnify_dev',
   },
-  typescript: {
-    outputDir: './types',
+
+  plugins: [
+    laravel({
+      migrationsPath: 'database/migrations',
+      typesPath: 'resources/js/types',
+      singleFile: true,
+    }),
+  ],
+});
+```
+
+### Configuration Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `schemasDir` | `string` | Yes | Directory containing schema files |
+| `lockFilePath` | `string` | Yes | Path to lock file for change tracking |
+| `database.driver` | `string` | Yes | Database driver: `mysql`, `postgres`, `sqlite` |
+| `database.devUrl` | `string` | Yes* | Development database URL for Atlas (*required for generate) |
+| `plugins` | `Plugin[]` | No | Array of generator plugins |
+
+### Database URL Format
+
+```
+mysql://user:password@host:port/database
+postgres://user:password@host:port/database
+sqlite://path/to/file.db
+```
+
+### Multiple Plugins
+
+```typescript
+import { defineConfig } from '@famgia/omnify';
+import laravel from '@famgia/omnify-laravel/plugin';
+// Future plugins
+// import prisma from '@famgia/omnify-prisma/plugin';
+// import drizzle from '@famgia/omnify-drizzle/plugin';
+
+export default defineConfig({
+  schemasDir: './schemas',
+  lockFilePath: './omnify.lock',
+
+  database: {
+    driver: 'mysql',
+    devUrl: 'mysql://root@localhost:3306/dev',
   },
+
+  plugins: [
+    // Laravel migrations + TypeScript types
+    laravel({
+      migrationsPath: 'database/migrations',
+      typesPath: 'resources/js/types',
+    }),
+
+    // Prisma schema (future)
+    // prisma({
+    //   schemaPath: 'prisma/schema.prisma',
+    // }),
+  ],
 });
 ```
 
+## Schema Files
+
+### Basic Schema
+
+`schemas/User.yaml`:
+```yaml
+name: User
+kind: object
+
+properties:
+  email:
+    type: Email
+    unique: true
+  name:
+    type: String
+  age:
+    type: Int
+    nullable: true
+
+options:
+  timestamps: true
+  softDeletes: true
+```
+
+### With Associations
+
+`schemas/Post.yaml`:
+```yaml
+name: Post
+kind: object
+
+properties:
+  title:
+    type: String
+  content:
+    type: Text
+  published:
+    type: Boolean
+    default: false
+
+associations:
+  author:
+    type: belongsTo
+    model: User
+    foreignKey: user_id
+
+options:
+  timestamps: true
+```
+
+### Enum
+
+`schemas/Status.yaml`:
+```yaml
+name: Status
+kind: enum
+
+values:
+  - draft
+  - published
+  - archived
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Validation error |
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `OMNIFY_DEV_URL` | Override database.devUrl from config |
+| `DEBUG` | Set to `omnify:*` for debug output |
+
+## Troubleshooting
+
+### "devUrl is required for generate command"
+
+Set your database URL in `omnify.config.ts`:
+```typescript
+database: {
+  driver: 'mysql',
+  devUrl: 'mysql://root:password@localhost:3306/dev_db',
+},
+```
+
+### "No schema files found"
+
+Make sure your `schemasDir` points to the correct directory and contains `.yaml` or `.json` files.
+
+### "Atlas command not found"
+
+Install Atlas CLI:
+```bash
+# macOS
+brew install ariga/tap/atlas
+
+# Linux
+curl -sSf https://atlasgo.sh | sh
+```
+
 ## Related Packages
 
+- [@famgia/omnify](https://www.npmjs.com/package/@famgia/omnify) - Main package
 - [@famgia/omnify-core](https://www.npmjs.com/package/@famgia/omnify-core) - Core engine
 - [@famgia/omnify-types](https://www.npmjs.com/package/@famgia/omnify-types) - Type definitions
 - [@famgia/omnify-laravel](https://www.npmjs.com/package/@famgia/omnify-laravel) - Laravel generator