@dbcube/cli 5.1.4 → 5.2.1

package/README.md

@@ -0,0 +1,59 @@
+# @dbcube/cli
+
+Command-line interface for [DBCube](https://www.npmjs.com/package/dbcube): schema management with `.cube` files, tracked migrations with rollback, seeders, triggers, TypeScript type generation and database introspection.
+
+## Installation
+
+```bash
+npm install -D @dbcube/cli
+npx dbcube init
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `npx dbcube init` | Scaffold a new project (config + `dbcube/` + example schema) |
+| `npx dbcube generate` | Generate TypeScript types from `.table.cube` files |
+| `npx dbcube validate` | Validate every `.cube` file without executing (exit 1 on errors — CI-friendly) |
+| `npx dbcube doctor` | Diagnose config, binaries and database connectivity |
+| `npx dbcube dev` | Watch mode: saving a `.cube` file applies it automatically |
+| `npx dbcube run database:create` | Interactive database setup (config + physical creation) |
+| `npx dbcube run table:fresh` | Drop and recreate all tables (asks for written confirmation; `--force` for CI) |
+| `npx dbcube run table:refresh` | Apply schema changes **without** dropping data |
+| `npx dbcube run table:alter` | Apply pending `.alter.cube` migrations (`--dry-run`, `--all`) |
+| `npx dbcube migrate:status` | Show applied / pending / modified migrations |
+| `npx dbcube migrate:rollback` | Revert the last migration batch |
+| `npx dbcube run pull [db]` | Generate `.table.cube` files FROM an existing database (MySQL, PostgreSQL, SQLite) |
+| `npx dbcube run seeder:add` | Run `.seeder.cube` data seeders |
+| `npx dbcube run trigger:fresh` | Recreate triggers from `.trigger.cube` files |
+| `npx dbcube update` | Check and update the Rust engine binaries |
+| `npx dbcube run download <engine> [ver]` | Download a specific engine binary |
+| `npx dbcube -v` | Versions of CLI, packages, engines, Node and platform |
+
+Run `npx dbcube help` for the full reference.
+
+## Configuration
+
+`dbcube.config.js` (created by `init`):
+
+```js
+module.exports = function (config) {
+    config.set({
+        databases: {
+            myapp: {
+                type: "sqlite", // mysql | postgres | sqlite | mongodb
+                config: { DATABASE: "myapp" }
+            }
+        }
+    });
+};
+```
+
+## Documentation
+
+https://dbcube.org
+
+## License
+
+MIT

package/package.json

@@ -1,22 +1,38 @@
 {
   "name": "@dbcube/cli",
-  "version": "5.1.4",
-  "main": "index.js",
+  "version": "5.2.1",
+  "main": "src/index.js",
   "scripts": {
     "dbcube": "node src/index.js"
   },
   "bin": {
     "dbcube": "./src/index.js"
   },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
-  "description": "",
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "dbcube",
+    "cli",
+    "database",
+    "migrations",
+    "mysql",
+    "postgresql",
+    "sqlite",
+    "orm"
+  ],
+  "author": "Albert Araya",
+  "license": "MIT",
+  "description": "Command-line interface for DBCube: schema management (.cube files), migrations with rollback, seeders, triggers, TypeScript type generation and database introspection.",
+  "publishConfig": {
+    "access": "public"
+  },
   "dependencies": {
-    "@dbcube/schema-builder": "^5.1.6",
-    "@inquirer/prompts": "^8.4.2",
+    "@dbcube/schema-builder": "^5.2.1",
+    "@inquirer/prompts": "^8.5.2",
     "alwait": "^1.0.0",
     "chalk": "4.1.2",
+    "dbcube": "^5.2.1",
     "dotenv": "^17.4.2",
     "fs-extra": "^11.3.5",
     "glob": "^13.0.6",

package/src/commands/dev.js

@@ -0,0 +1,83 @@
+const fs = require('fs');
+const path = require('path');
+const chalk = require('chalk');
+const { execSync } = require('child_process');
+
+/**
+ * dbcube dev — Watch mode: edits to .cube files apply automatically.
+ *   *.table.cube   → table:refresh
+ *   *.trigger.cube → trigger:fresh
+ *   *.seeder.cube  → hint (seeders insert data; never auto-run)
+ *   *.alter.cube   → hint (migrations are explicit; run table:alter)
+ * Regenerates dbcube/types.ts when it exists.
+ */
+const DEBOUNCE_MS = 600;
+let timer = null;
+const pendingKinds = new Set();
+
+function runCli(args) {
+    try {
+        execSync(`node "${path.join(__dirname, '..', 'index.js')}" ${args}`, {
+            stdio: 'inherit',
+            cwd: process.cwd(),
+        });
+    } catch { /* errors already printed by the subcommand */ }
+}
+
+function flush() {
+    timer = null;
+    const kinds = [...pendingKinds];
+    pendingKinds.clear();
+
+    if (kinds.includes('table')) {
+        console.log(`\n${chalk.cyan('↻')} ${chalk.bold('table change detected')} → table:refresh`);
+        runCli('run table:refresh');
+        if (fs.existsSync(path.join(process.cwd(), 'dbcube', 'types.ts'))) {
+            runCli('generate');
+        }
+    }
+    if (kinds.includes('trigger')) {
+        console.log(`\n${chalk.cyan('↻')} ${chalk.bold('trigger change detected')} → trigger:fresh`);
+        runCli('run trigger:fresh');
+    }
+    if (kinds.includes('seeder')) {
+        console.log(`\n${chalk.gray('ℹ seeder changed — run when ready:')} ${chalk.white('npx dbcube run seeder:add')}`);
+    }
+    if (kinds.includes('alter')) {
+        console.log(`\n${chalk.gray('ℹ alter file changed — apply explicitly:')} ${chalk.white('npx dbcube run table:alter')}`);
+    }
+    console.log(`\n${chalk.green('👀 watching dbcube/ ...')} ${chalk.gray('(Ctrl+C to stop)')}`);
+}
+
+function onChange(filename) {
+    if (!filename || !filename.endsWith('.cube')) return;
+    if (filename.includes('triggers' + path.sep) || filename.includes('logs' + path.sep)) return;
+
+    if (filename.endsWith('.table.cube')) pendingKinds.add('table');
+    else if (filename.endsWith('.trigger.cube')) pendingKinds.add('trigger');
+    else if (filename.endsWith('.seeder.cube')) pendingKinds.add('seeder');
+    else if (filename.endsWith('.alter.cube')) pendingKinds.add('alter');
+    else return;
+
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(flush, DEBOUNCE_MS);
+}
+
+async function main() {
+    const cubesDir = path.join(process.cwd(), 'dbcube');
+    if (!fs.existsSync(cubesDir)) {
+        console.error(`${chalk.red('❌')} dbcube/ directory not found — run: npx dbcube init`);
+        process.exit(1);
+    }
+
+    console.log(`\n${chalk.green.bold('🚀 DBCube dev mode')}`);
+    console.log(`${chalk.gray('Save a .cube file and the change applies automatically.')}\n`);
+    console.log(`${chalk.green('👀 watching dbcube/ ...')} ${chalk.gray('(Ctrl+C to stop)')}`);
+
+    fs.watch(cubesDir, { recursive: true }, (_event, filename) => onChange(filename));
+}
+
+main().catch(error => {
+    console.error('Error fatal:', error);
+    process.exit(1);
+});

package/src/commands/doctor.js

@@ -0,0 +1,99 @@
+const fs = require('fs');
+const path = require('path');
+const chalk = require('chalk');
+const ConfigFileUtils = require('../utils/ConfigFileUtils');
+const { Engine } = require('@dbcube/schema-builder');
+
+/**
+ * dbcube doctor — Diagnoses the project setup: config file, databases,
+ * connectivity, cube files, and environment. Kills 80% of support issues.
+ */
+const ok = (msg) => console.log(`  ${chalk.green('✓')} ${msg}`);
+const warn = (msg) => console.log(`  ${chalk.yellow('⚠')} ${msg}`);
+const fail = (msg) => console.log(`  ${chalk.red('✗')} ${msg}`);
+
+async function main() {
+    console.log(`\n🩺 ${chalk.green.bold('DBCube Doctor')}\n`);
+    let problems = 0;
+
+    // 1. Node version
+    const major = parseInt(process.versions.node.split('.')[0], 10);
+    if (major >= 16) ok(`Node.js ${process.versions.node}`);
+    else { fail(`Node.js ${process.versions.node} — DBCube requires >= 16`); problems++; }
+
+    // 2. Config file
+    const configPath = path.join(process.cwd(), 'dbcube.config.js');
+    if (!fs.existsSync(configPath)) {
+        fail('dbcube.config.js not found — run: npx dbcube init');
+        problems++;
+    } else {
+        ok('dbcube.config.js found');
+    }
+
+    // 3. Configured databases
+    let databases = [];
+    try {
+        databases = await ConfigFileUtils.getConfiguredDatabases();
+        if (databases.length === 0) { warn('No databases configured — run: npx dbcube run database:create'); }
+        else ok(`${databases.length} database(s) configured: ${databases.map(d => `${d.name} (${d.type})`).join(', ')}`);
+    } catch (e) {
+        fail(`dbcube.config.js could not be loaded: ${e.message}`);
+        problems++;
+    }
+
+    // 4. Cube files
+    const cubesDir = path.join(process.cwd(), 'dbcube');
+    if (fs.existsSync(cubesDir)) {
+        const count = (dir) => fs.readdirSync(dir, { withFileTypes: true }).reduce((acc, e) => {
+            const full = path.join(dir, e.name);
+            if (e.isDirectory() && !['triggers', 'logs'].includes(e.name)) return acc + count(full);
+            return acc + (e.name.endsWith('.cube') ? 1 : 0);
+        }, 0);
+        const n = count(cubesDir);
+        if (n > 0) ok(`${n} .cube file(s) in dbcube/`);
+        else warn('dbcube/ exists but has no .cube files');
+    } else {
+        warn('dbcube/ directory not found — run: npx dbcube init');
+    }
+
+    // 5. Connectivity per database (also verifies engine binaries)
+    for (const db of databases) {
+        try {
+            const engine = new Engine(db.name);
+            const response = await engine.run('query_engine', ['--action', 'connect']);
+            if (response.status === 200 || /persistente|Listo|created/i.test(response.message || '')) {
+                ok(`Connection OK: ${db.name} (${db.type})`);
+            } else {
+                fail(`Connection failed: ${db.name} — ${response.message}`);
+                problems++;
+            }
+        } catch (e) {
+            fail(`Connection failed: ${db.name} — ${e.message}`);
+            problems++;
+        }
+    }
+
+    // 6. Daemon status
+    const daemonDir = path.join(process.cwd(), '.dbcube', 'daemon');
+    if (fs.existsSync(daemonDir)) {
+        const portfiles = fs.readdirSync(daemonDir).filter(f => f.endsWith('.json'));
+        if (portfiles.length > 0) ok(`Daemon mode active for: ${portfiles.map(f => path.basename(f, '.json')).join(', ')}`);
+        else warn('No active daemons (first query will start one automatically)');
+    } else {
+        warn('No active daemons (first query will start one automatically)');
+    }
+
+    console.log('');
+    if (problems === 0) {
+        console.log(`${chalk.green.bold('✅ Everything looks healthy!')}\n`);
+    } else {
+        console.log(`${chalk.red.bold(`❌ ${problems} problem(s) found`)}\n`);
+        process.exit(1);
+    }
+    process.exit(0);
+}
+
+main().catch(error => {
+    console.error('Error fatal:', error);
+    process.exit(1);
+});

package/src/commands/generate.js

@@ -0,0 +1,160 @@
+const fs = require('fs');
+const path = require('path');
+const chalk = require('chalk');
+
+/**
+ * dbcube generate — Generates TypeScript interfaces from .table.cube files.
+ * Output: dbcube/types.ts (one interface per table + DbSchema map).
+ *
+ * Usage with the query builder:
+ *   import type { User } from './dbcube/types';
+ *   const users = await db.table('users').get() as User[];
+ */
+const TYPE_MAP = {
+    int: 'number', integer: 'number', bigint: 'number', tinyint: 'number',
+    float: 'number', double: 'number', decimal: 'number',
+    varchar: 'string', string: 'string', text: 'string', uuid: 'string',
+    date: 'string', datetime: 'string', timestamp: 'string',
+    boolean: 'boolean', bool: 'boolean',
+    json: 'any',
+};
+
+function collectTableCubes(dir, acc = []) {
+    if (!fs.existsSync(dir)) return acc;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (!['triggers', 'logs', 'node_modules'].includes(entry.name)) collectTableCubes(full, acc);
+        } else if (entry.name.endsWith('.table.cube')) {
+            acc.push(full);
+        }
+    }
+    return acc;
+}
+
+function pascalCase(name) {
+    return name.split(/[_\-\s]+/).map(w => w.charAt(0).toUpperCase() + w.slice(1)).join('');
+}
+
+function singularize(word) {
+    if (word.endsWith('ies')) return word.slice(0, -3) + 'y';
+    if (word.endsWith('ses')) return word.slice(0, -2);
+    if (word.endsWith('s') && !word.endsWith('ss')) return word.slice(0, -1);
+    return word;
+}
+
+/** Parses the @columns block of a .table.cube into [{name, tsType, optional, comment}] */
+function parseCube(content) {
+    const nameMatch = content.match(/@meta\s*\(\s*\{[\s\S]*?name\s*:\s*"([^"]+)"/);
+    const dbMatch = content.match(/@database\s*\(\s*"([^"]+)"\s*\)/);
+    const columnsMatch = content.match(/@columns\s*\(\s*\{([\s\S]*)\}\s*\)\s*;?\s*$/m)
+        || content.match(/@columns\s*\(\s*\{([\s\S]*?)\}\s*\)\s*;/);
+    if (!columnsMatch) return null;
+
+    const body = columnsMatch[1];
+    const columns = [];
+    // Match each top-level "col: { ... };" block (tolerates one nesting level: foreign/@compute braces)
+    const colRegex = /(\w+)\s*:\s*\{((?:[^{}]|\{(?:[^{}]|\{[^{}]*\})*\})*?)\}\s*;/g;
+    let m;
+    while ((m = colRegex.exec(body)) !== null) {
+        const colName = m[1];
+        const def = m[2];
+        const typeMatch = def.match(/type\s*:\s*"([^"]+)"/);
+        if (!typeMatch) continue;
+        const cubeType = typeMatch[1].toLowerCase();
+
+        let tsType = TYPE_MAP[cubeType] ?? 'any';
+        if (cubeType === 'enum') {
+            const enumMatch = def.match(/enumValues\s*:\s*\[([^\]]*)\]/);
+            if (enumMatch) {
+                const values = enumMatch[1].match(/"([^"]*)"/g);
+                if (values && values.length > 0) tsType = values.join(' | ');
+            }
+        }
+
+        const options = (def.match(/options\s*:\s*\[([^\]]*)\]/) || [])[1] || '';
+        const notNull = /"not null"/.test(options) || /"primary"/.test(options);
+        const hasDefault = /defaultValue\s*:/.test(def) || /"autoincrement"/.test(options);
+        const isComputed = /@compute/.test(def);
+
+        columns.push({
+            name: colName,
+            tsType: notNull ? tsType : `${tsType} | null`,
+            optional: !notNull || hasDefault || isComputed,
+            comment: isComputed ? 'computed field (read-only, requires useComputes())' : null,
+        });
+    }
+
+    return {
+        table: nameMatch ? nameMatch[1] : null,
+        database: dbMatch ? dbMatch[1] : null,
+        columns,
+    };
+}
+
+async function main() {
+    const cubesDir = path.join(process.cwd(), 'dbcube');
+    const files = collectTableCubes(cubesDir);
+
+    if (files.length === 0) {
+        console.log(`${chalk.yellow('⚠')} No .table.cube files found in dbcube/`);
+        process.exit(0);
+    }
+
+    console.log(`\n🧬 ${chalk.green('Generating TypeScript types from')} ${files.length} cube(s)...\n`);
+
+    let out = `// ⚠ AUTO-GENERATED by \`dbcube generate\` — do not edit by hand.\n`;
+    out += `// Source of truth: your .table.cube files. Re-run after schema changes.\n\n`;
+
+    const schemaEntries = [];
+
+    for (const file of files) {
+        const content = fs.readFileSync(file, 'utf8');
+        const parsed = parseCube(content);
+        const tableName = (parsed && parsed.table) || path.basename(file, '.table.cube');
+
+        if (!parsed || parsed.columns.length === 0) {
+            console.log(`  ${chalk.yellow('⚠')} ${path.relative(process.cwd(), file)} — could not parse columns, skipped`);
+            continue;
+        }
+
+        const ifaceName = pascalCase(singularize(tableName));
+        out += `/** Table \`${tableName}\`${parsed.database ? ` · database \`${parsed.database}\`` : ''} */\n`;
+        out += `export interface ${ifaceName} {\n`;
+        for (const col of parsed.columns) {
+            if (col.comment) out += `    /** ${col.comment} */\n`;
+            out += `    ${col.name}: ${col.tsType};\n`;
+        }
+        out += `}\n\n`;
+
+        out += `/** Shape accepted by insert()/update() for \`${tableName}\` */\n`;
+        out += `export interface New${ifaceName} {\n`;
+        for (const col of parsed.columns) {
+            if (col.comment) continue; // computed fields are not writable
+            out += `    ${col.name}${col.optional ? '?' : ''}: ${col.tsType};\n`;
+        }
+        out += `}\n\n`;
+
+        schemaEntries.push({ tableName, ifaceName });
+        console.log(`  ${chalk.green('✓')} ${tableName} → ${ifaceName}, New${ifaceName}`);
+    }
+
+    out += `/** Map of table name → row type. */\n`;
+    out += `export interface DbSchema {\n`;
+    for (const { tableName, ifaceName } of schemaEntries) {
+        out += `    ${tableName}: ${ifaceName};\n`;
+    }
+    out += `}\n`;
+
+    const outPath = path.join(cubesDir, 'types.ts');
+    fs.writeFileSync(outPath, out, 'utf8');
+    console.log(`\n${chalk.green('✓')} Types written to ${chalk.bold('dbcube/types.ts')}\n`);
+    console.log(`${chalk.cyan('Usage:')}`);
+    console.log(`  import type { ${schemaEntries[0] ? schemaEntries[0].ifaceName : 'User'} } from './dbcube/types';`);
+    console.log(`  const rows = await db.table('${schemaEntries[0] ? schemaEntries[0].tableName : 'users'}').get() as ${schemaEntries[0] ? schemaEntries[0].ifaceName : 'User'}[];\n`);
+}
+
+main().catch(error => {
+    console.error('Error fatal:', error);
+    process.exit(1);
+});

package/src/commands/help.js

@@ -10,7 +10,14 @@ async function showHelp() {
         
         console.log(`${chalk.cyan.bold('USAGE:')}`);
         console.log(`  ${chalk.white('npx dbcube')} ${chalk.yellow('<command>')} ${chalk.gray('[options]')}\n`);
-        
+
+        console.log(`${chalk.cyan.bold('PROJECT COMMANDS:')}`);
+        console.log(`  ${chalk.yellow('init')}                      ${chalk.white('Scaffold a new DBCube project (config + dbcube/ + example)')}`);
+        console.log(`  ${chalk.yellow('generate')}                  ${chalk.white('Generate TypeScript types from .table.cube files')}`);
+        console.log(`  ${chalk.yellow('validate')}                  ${chalk.white('Validate every .cube file without executing (CI-friendly)')}`);
+        console.log(`  ${chalk.yellow('doctor')}                    ${chalk.white('Diagnose config, binaries, and database connectivity')}`);
+        console.log(`  ${chalk.yellow('dev')}                       ${chalk.white('Watch mode: .cube changes apply automatically')}\n`);
+
         console.log(`${chalk.cyan.bold('DATABASE COMMANDS:')}`);
         console.log(`  ${chalk.yellow('database:create')}           ${chalk.white('Create a new database with interactive setup')}`);
         console.log(`  ${chalk.yellow('run database:create')}       ${chalk.white('Alternative syntax for database creation')}`);
@@ -20,7 +27,13 @@ async function showHelp() {
         console.log(`${chalk.cyan.bold('TABLE COMMANDS:')}`);
         console.log(`  ${chalk.yellow('run table:fresh')}           ${chalk.white('Drop and recreate all tables from .cube files')}`);
         console.log(`  ${chalk.yellow('run table:refresh')}         ${chalk.white('Refresh table structures without dropping data')}`);
-        console.log(`  ${chalk.yellow('run table:alter')}           ${chalk.white('Apply ALTER TABLE changes from .alter.cube files')}\n`);
+        console.log(`  ${chalk.yellow('run table:alter')}           ${chalk.white('Apply PENDING .alter.cube migrations (tracked)')}`);
+        console.log(`  ${chalk.gray('  Options:')} --dry-run ${chalk.gray('(print SQL only)')} · --all ${chalk.gray('(ignore history)')}\n`);
+
+        console.log(`${chalk.cyan.bold('MIGRATION COMMANDS:')}`);
+        console.log(`  ${chalk.yellow('migrate:status')}            ${chalk.white('Show applied and pending migrations')}`);
+        console.log(`  ${chalk.yellow('migrate:rollback')}          ${chalk.white('Revert the last applied migration batch')}`);
+        console.log(`  ${chalk.yellow('run pull [database]')}       ${chalk.white('Generate .table.cube files FROM an existing database')}\n`);
         
         console.log(`${chalk.cyan.bold('TRIGGER COMMANDS:')}`);
         console.log(`  ${chalk.yellow('run trigger:fresh')}         ${chalk.white('Recreate all database triggers from .cube files')}\n`);
@@ -67,12 +80,15 @@ async function showHelp() {
         console.log(`  ${chalk.white('npx dbcube update')}\n`);
         
         console.log(`${chalk.cyan.bold('CONFIGURATION:')}`);
-        console.log(`  ${chalk.white('Create a')} ${chalk.yellow('dbcube.config.js')} ${chalk.white('file in your project root:')}`);
-        console.log(`  ${chalk.gray('module.exports = (config) => {')}`);
-        console.log(`  ${chalk.gray('  config.addDatabase({')}`);
-        console.log(`  ${chalk.gray('    name: "myapp",')}`);
-        console.log(`  ${chalk.gray('    type: "sqlite", // mysql, postgres, sqlite, mongodb')}`);
-        console.log(`  ${chalk.gray('    // ... connection settings')}`);
+        console.log(`  ${chalk.white('Create a')} ${chalk.yellow('dbcube.config.js')} ${chalk.white('file in your project root (or run')} ${chalk.yellow('npx dbcube init')}${chalk.white('):')}`);
+        console.log(`  ${chalk.gray("module.exports = function (config) {")}`);
+        console.log(`  ${chalk.gray('  config.set({')}`);
+        console.log(`  ${chalk.gray('    databases: {')}`);
+        console.log(`  ${chalk.gray('      myapp: {')}`);
+        console.log(`  ${chalk.gray('        type: "sqlite", // mysql, postgres, sqlite, mongodb')}`);
+        console.log(`  ${chalk.gray('        config: { DATABASE: process.env.DBCUBE_MYAPP_DATABASE }')}`);
+        console.log(`  ${chalk.gray('      }')}`);
+        console.log(`  ${chalk.gray('    }')}`);
         console.log(`  ${chalk.gray('  });')}`);
         console.log(`  ${chalk.gray('};')}\n`);
         

package/src/commands/init.js

@@ -0,0 +1,82 @@
+const fs = require('fs');
+const path = require('path');
+const chalk = require('chalk');
+const ConfigFileUtils = require('../utils/ConfigFileUtils');
+
+/**
+ * dbcube init — Scaffolds a new DBCube project:
+ * dbcube.config.js + .env + dbcube/ with an example .table.cube
+ */
+async function main() {
+    const root = process.cwd();
+    console.log(`\n💚 ${chalk.green('Initializing DBCube project...')}\n`);
+
+    // 1. dbcube.config.js
+    const configPath = path.join(root, 'dbcube.config.js');
+    if (fs.existsSync(configPath)) {
+        console.log(`  ${chalk.yellow('•')} dbcube.config.js already exists — skipped`);
+    } else {
+        ConfigFileUtils.crearArchivoConfig(configPath);
+        console.log(`  ${chalk.green('✓')} dbcube.config.js created`);
+    }
+
+    // 2. dbcube/ directory
+    const cubesDir = path.join(root, 'dbcube');
+    if (!fs.existsSync(cubesDir)) {
+        fs.mkdirSync(cubesDir, { recursive: true });
+        console.log(`  ${chalk.green('✓')} dbcube/ directory created`);
+    } else {
+        console.log(`  ${chalk.yellow('•')} dbcube/ already exists — skipped`);
+    }
+
+    // 3. Example table cube
+    const examplePath = path.join(cubesDir, 'example.table.cube');
+    if (!fs.existsSync(examplePath) && fs.readdirSync(cubesDir).filter(f => f.endsWith('.cube')).length === 0) {
+        fs.writeFileSync(examplePath, `@database("local");
+
+@meta({
+    name: "example";
+    description: "Example table - rename or delete this file";
+});
+
+@columns({
+    id: {
+        type: "int";
+        options: ["primary", "autoincrement"];
+    };
+    name: {
+        type: "varchar";
+        length: "255";
+        options: ["not null"];
+    };
+    created_at: {
+        type: "timestamp";
+        options: ["not null"];
+    };
+});
+`, 'utf8');
+        console.log(`  ${chalk.green('✓')} dbcube/example.table.cube created`);
+    }
+
+    // 4. .gitignore entries
+    const gitignorePath = path.join(root, '.gitignore');
+    const entries = ['.dbcube/', 'dbcube/triggers/', 'dbcube/logs/', '.env'];
+    let gitignore = fs.existsSync(gitignorePath) ? fs.readFileSync(gitignorePath, 'utf8') : '';
+    const missing = entries.filter(e => !gitignore.split('\n').some(l => l.trim() === e));
+    if (missing.length > 0) {
+        gitignore += (gitignore.endsWith('\n') || gitignore === '' ? '' : '\n') + '\n# DBCube\n' + missing.join('\n') + '\n';
+        fs.writeFileSync(gitignorePath, gitignore, 'utf8');
+        console.log(`  ${chalk.green('✓')} .gitignore updated (${missing.join(', ')})`);
+    }
+
+    console.log(`\n${chalk.cyan.bold('Next steps:')}`);
+    console.log(`  1. ${chalk.white('npx dbcube run database:create')}   ${chalk.gray('— configure your first database')}`);
+    console.log(`  2. ${chalk.white('Edit dbcube/example.table.cube')}   ${chalk.gray('— define your schema')}`);
+    console.log(`  3. ${chalk.white('npx dbcube run table:fresh')}       ${chalk.gray('— create the tables')}`);
+    console.log(`  4. ${chalk.white('npx dbcube generate')}              ${chalk.gray('— generate TypeScript types')}\n`);
+}
+
+main().catch(error => {
+    console.error('Error fatal:', error);
+    process.exit(1);
+});