Add REPL command to CLI and project example

Introduces a new 'repl' command to the CLI, enabling an interactive shell for querying the database using ObjectQL. Updates documentation with usage instructions, adds a sample configuration and SQLite database to the project-management example, and updates dependencies to include required drivers.

Author: hotlong

docs/guide/cli.md

@@ -38,7 +38,36 @@ npx objectql generate [options]
 npx objectql generate --source ./src/objects --output ./src/types
 ```
 
-### 2.2 `migration` (Coming Soon)
+### 2.2 `repl` (Interactive Shell)
+
+Starts an interactive terminal similar to the MongoDB shell, allowing you to directly query your database using the ObjectQL API.
+
+**Prerequisites:**
+
+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`).
+
+**Usage:**
+
+```bash
+npx objectql repl
+```
+
+**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.
+
+**Example Session:**
+
+```javascript
+objectql> await tasks.find({ status: 'todo' })
+[ { id: 1, title: 'Fix bug', status: 'todo' } ]
+
+objectql> await projects.create({ name: 'New API' })
+{ id: 10, name: 'New API', ... }
+```
+
+### 2.3 `migration` (Coming Soon)
 
 Future versions will include migration commands to sync your YAML schema with the database.
 

examples/project-management/dev.sqlite3

@@ -0,0 +1,21 @@
+import { ObjectQL, MetadataLoader } from '@objectql/core';
+import { KnexDriver } from '@objectql/driver-knex';
+import * as path from 'path';
+
+const app = new ObjectQL({
+    datasources: {
+        default: new KnexDriver({
+            client: 'sqlite3',
+            connection: {
+                filename: path.join(__dirname, 'dev.sqlite3')
+            },
+            useNullAsDefault: true
+        })
+    }
+});
+
+// Load objects from src
+const loader = new MetadataLoader(app.metadata);
+loader.load(path.join(__dirname, 'src')); 
+
+export default app;

examples/project-management/objectql.config.ts

@@ -10,11 +10,14 @@
   "scripts": {
     "codegen": "objectql generate -s src -o src",
     "build": "npm run codegen && tsc && cp src/*.yml dist/",
+    "repl": "objectql repl",
     "test": "echo \"No tests specified\" && exit 0"
   },
   "peerDependencies": {
     "@objectql/core": "workspace:*",
-    "@objectql/types": "workspace:*"
+    "@objectql/types": "workspace:*",
+    "@objectql/driver-knex": "workspace:*",
+    "sqlite3": "^5.1.7"
   },
   "devDependencies": {
     "@objectql/core": "workspace:*",

examples/project-management/package.json

@@ -0,0 +1,98 @@
+import * as repl from 'repl';
+import * as path from 'path';
+import * as fs from 'fs';
+import { ObjectQL } from '@objectql/core';
+import { register } from 'ts-node';
+
+export async function startRepl(configPath?: string) {
+    const cwd = process.cwd();
+    
+    // Register ts-node to handle TS config loading
+    register({
+        transpileOnly: true,
+        compilerOptions: {
+            module: "commonjs"
+        }
+    });
+
+    // 1. Resolve Config File
+    let configFile = configPath;
+    if (!configFile) {
+        const potentialFiles = ['objectql.config.ts', 'objectql.config.js'];
+        for (const file of potentialFiles) {
+            if (fs.existsSync(path.join(cwd, file))) {
+                configFile = file;
+                break;
+            }
+        }
+    }
+
+    if (!configFile) {
+        console.error("❌ No configuration file found (objectql.config.ts/js).");
+        console.log("Please create one that exports an ObjectQL instance.");
+        process.exit(1);
+    }
+
+    console.log(`🚀 Loading configuration from ${configFile}...`);
+    
+    try {
+        const configModule = require(path.join(cwd, configFile));
+        // Support default export or named export 'app' or 'objectql'
+        const app = configModule.default || configModule.app || configModule.objectql;
+
+        if (!(app instanceof ObjectQL)) {
+            console.error("❌ The config file must export an instance of 'ObjectQL' as default or 'app'.");
+            process.exit(1);
+        }
+
+        // 2. Init ObjectQL
+        await app.init();
+        console.log("✅ ObjectQL Initialized.");
+
+        // 3. Start REPL
+        const r = repl.start({
+            prompt: 'objectql> ',
+            useColors: true
+        });
+
+        // 4. Inject Context
+        r.context.app = app;
+        r.context.object = (name: string) => app.getObject(name);
+        
+        // Helper to get a repo quickly: tasks.find() instead of app.object('tasks').find()
+        const objects = app.metadata.list('object');
+        for (const obj of objects) {
+            // Inject repositories as top-level globals if valid identifiers
+            if (/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(obj.name)) {
+                // We use a getter to lazily create context with system privileges
+                Object.defineProperty(r.context, obj.name, {
+                    get: () => {
+                        // HACK: We need to construct a repository. 
+                        // Since `ObjectRepository` is exported from `@objectql/core`, we can use it if we import it.
+                        // But `app` is passed from user land. We can rely on `require('@objectql/core')` here.
+                        const { ObjectRepository } = require('@objectql/core');
+                        
+                        const replContext: any = {
+                            roles: ['admin'],
+                            isSystem: true,
+                            userId: 'REPL'
+                        };
+                        
+                        replContext.object = (n: string) => new ObjectRepository(n, replContext, app);
+                        replContext.transaction = async (cb: any) => cb(replContext);
+                        replContext.sudo = () => replContext;
+
+                        return new ObjectRepository(obj.name, replContext, app);
+                    }
+                });
+            }
+        }
+
+        console.log(`\nAvailable Objects: ${objects.map((o: any) => o.name).join(', ')}`);
+        console.log(`Usage: await tasks.find()`);
+
+    } catch (error) {
+        console.error("Failed to load or start:", error);
+        process.exit(1);
+    }
+}

packages/cli/src/commands/repl.ts

@@ -1,5 +1,6 @@
 import { Command } from 'commander';
 import { generateTypes } from './commands/generate';
+import { startRepl } from './commands/repl';
 
 const program = new Command();
 
@@ -23,4 +24,13 @@ program
         }
     });
 
+program
+    .command('repl')
+    .alias('r')
+    .description('Start an interactive shell (REPL) to query the database')
+    .option('-c, --config <path>', 'Path to objectql.config.ts/js')
+    .action(async (options) => {
+        await startRepl(options.config);
+    });
+
 program.parse();