@grafema/cli 0.2.1-beta → 0.2.3-beta

package/dist/cli.js

@@ -3,6 +3,9 @@
  * @grafema/cli - CLI for Grafema code analysis toolkit
  */
 import { Command } from 'commander';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
 import { initCommand } from './commands/init.js';
 import { analyzeCommand } from './commands/analyze.js';
 import { overviewCommand } from './commands/overview.js';
@@ -20,11 +23,14 @@ import { coverageCommand } from './commands/coverage.js';
 import { doctorCommand } from './commands/doctor.js';
 import { schemaCommand } from './commands/schema.js';
 import { explainCommand } from './commands/explain.js';
+// Read version from package.json
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
 const program = new Command();
 program
     .name('grafema')
     .description('Grafema code analysis CLI')
-    .version('0.1.0-alpha.1');
+    .version(pkg.version);
 // Commands in logical order
 program.addCommand(initCommand);
 program.addCommand(analyzeCommand);

package/dist/commands/analyze.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../../src/commands/analyze.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgLpC,eAAO,MAAM,cAAc,SAqKvB,CAAC"}
+{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../../src/commands/analyze.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgLpC,eAAO,MAAM,cAAc,SAgMvB,CAAC"}

package/dist/commands/analyze.js

@@ -135,6 +135,7 @@ export const analyzeCommand = new Command('analyze')
     .option('--debug', 'Enable debug mode (writes diagnostics.log)')
     .option('--log-level <level>', 'Set log level (silent, errors, warnings, info, debug)')
     .option('--strict', 'Enable strict mode (fail on unresolved references)')
+    .option('--auto-start', 'Auto-start RFDB server if not running')
     .addHelpText('after', `
 Examples:
   grafema analyze                Analyze current project
@@ -144,6 +145,9 @@ Examples:
   grafema analyze -v             Verbose output with progress details
   grafema analyze --debug        Write diagnostics.log for debugging
   grafema analyze --strict       Fail on unresolved references (debugging)
+  grafema analyze --auto-start   Auto-start server (useful for CI)
+
+Note: Start the server first with: grafema server start
 `)
     .action(async (path, options) => {
     const projectPath = resolve(path);
@@ -157,8 +161,31 @@ Examples:
     const logLevel = getLogLevel(options);
     const logger = createLogger(logLevel);
     log(`Analyzing project: ${projectPath}`);
-    const backend = new RFDBServerBackend({ dbPath });
-    await backend.connect();
+    // Connect to RFDB server
+    // Default: require explicit `grafema server start`
+    // Use --auto-start for CI or backwards compatibility
+    const backend = new RFDBServerBackend({
+        dbPath,
+        autoStart: options.autoStart ?? false
+    });
+    try {
+        await backend.connect();
+    }
+    catch (err) {
+        if (!options.autoStart && err instanceof Error && err.message.includes('not running')) {
+            console.error('');
+            console.error('RFDB server is not running.');
+            console.error('');
+            console.error('Start the server first:');
+            console.error('  grafema server start');
+            console.error('');
+            console.error('Or use --auto-start flag:');
+            console.error('  grafema analyze --auto-start');
+            console.error('');
+            process.exit(1);
+        }
+        throw err;
+    }
     if (options.clear) {
         log('Clearing existing database...');
         await backend.clear();

package/dist/commands/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/commands/server.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA+FpC,eAAO,MAAM,aAAa,SAQxB,CAAC"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/commands/server.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAoHpC,eAAO,MAAM,aAAa,SAaxB,CAAC"}

package/dist/commands/server.js

@@ -12,18 +12,39 @@ import { existsSync, unlinkSync, writeFileSync, readFileSync } from 'fs';
 import { spawn } from 'child_process';
 import { fileURLToPath } from 'url';
 import { setTimeout as sleep } from 'timers/promises';
-import { RFDBClient } from '@grafema/core';
+import { RFDBClient, loadConfig } from '@grafema/core';
 import { exitWithError } from '../utils/errorFormatter.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 /**
  * Find RFDB server binary in order of preference:
- * 1. @grafema/rfdb npm package
- * 2. packages/rfdb-server/target/release (monorepo development)
- * 3. packages/rfdb-server/target/debug
+ * 1. Explicit path (from --binary flag or config)
+ * 2. Monorepo development (target/release, target/debug)
+ * 3. @grafema/rfdb npm package (prebuilt binaries)
+ * 4. ~/.local/bin/rfdb-server (user-installed)
  */
-function findServerBinary() {
-    // 1. Check @grafema/rfdb npm package
+function findServerBinary(explicitPath) {
+    // 1. Explicit path from --binary flag or config
+    if (explicitPath) {
+        const resolved = resolve(explicitPath);
+        if (existsSync(resolved)) {
+            return resolved;
+        }
+        // Explicit path specified but not found - this is an error
+        console.error(`Specified binary not found: ${resolved}`);
+        return null;
+    }
+    // 2. Check packages/rfdb-server in monorepo (for development)
+    const projectRoot = join(__dirname, '../../../..');
+    const releaseBinary = join(projectRoot, 'packages/rfdb-server/target/release/rfdb-server');
+    if (existsSync(releaseBinary)) {
+        return releaseBinary;
+    }
+    const debugBinary = join(projectRoot, 'packages/rfdb-server/target/debug/rfdb-server');
+    if (existsSync(debugBinary)) {
+        return debugBinary;
+    }
+    // 3. Check @grafema/rfdb npm package
     try {
         const rfdbPkg = require.resolve('@grafema/rfdb');
         const rfdbDir = dirname(rfdbPkg);
@@ -47,17 +68,10 @@ function findServerBinary() {
     catch {
         // @grafema/rfdb not installed
     }
-    // 2. Check packages/rfdb-server in monorepo
-    // From packages/cli/dist/commands -> project root is 4 levels up
-    const projectRoot = join(__dirname, '../../../..');
-    const releaseBinary = join(projectRoot, 'packages/rfdb-server/target/release/rfdb-server');
-    if (existsSync(releaseBinary)) {
-        return releaseBinary;
-    }
-    // 3. Check debug build
-    const debugBinary = join(projectRoot, 'packages/rfdb-server/target/debug/rfdb-server');
-    if (existsSync(debugBinary)) {
-        return debugBinary;
+    // 4. Check ~/.local/bin (user-installed binary for unsupported platforms)
+    const homeBinary = join(process.env.HOME || '', '.local', 'bin', 'rfdb-server');
+    if (existsSync(homeBinary)) {
+        return homeBinary;
     }
     return null;
 }
@@ -97,16 +111,22 @@ export const serverCommand = new Command('server')
     .description('Manage RFDB server lifecycle')
     .addHelpText('after', `
 Examples:
-  grafema server start           Start the RFDB server (detached)
-  grafema server stop            Stop the running server
-  grafema server status          Check if server is running
-  grafema server status --json   Server status as JSON
+  grafema server start                       Start the RFDB server
+  grafema server start --binary /path/to/bin Start with specific binary
+  grafema server stop                        Stop the running server
+  grafema server status                      Check if server is running
+  grafema server status --json               Server status as JSON
+
+Config (in .grafema/config.yaml):
+  server:
+    binaryPath: /path/to/rfdb-server    # Optional: path to binary
 `);
 // grafema server start
 serverCommand
     .command('start')
     .description('Start the RFDB server')
     .option('-p, --project <path>', 'Project path', '.')
+    .option('-b, --binary <path>', 'Path to rfdb-server binary')
     .action(async (options) => {
     const projectPath = resolve(options.project);
     const { grafemaDir, socketPath, dbPath, pidPath } = getProjectPaths(projectPath);
@@ -130,15 +150,41 @@ serverCommand
     if (existsSync(socketPath)) {
         unlinkSync(socketPath);
     }
-    // Find server binary
-    const binaryPath = findServerBinary();
+    // Determine binary path: CLI flag > config > auto-detect
+    let binaryPath = null;
+    if (options.binary) {
+        // Explicit --binary flag
+        binaryPath = findServerBinary(options.binary);
+    }
+    else {
+        // Try to read from config
+        try {
+            const config = loadConfig(projectPath);
+            const serverConfig = config.server;
+            if (serverConfig?.binaryPath) {
+                binaryPath = findServerBinary(serverConfig.binaryPath);
+            }
+        }
+        catch {
+            // Config not found or invalid - continue with auto-detect
+        }
+        // Auto-detect if not specified
+        if (!binaryPath) {
+            binaryPath = findServerBinary();
+        }
+    }
     if (!binaryPath) {
         exitWithError('RFDB server binary not found', [
-            'Install: npm install @grafema/rfdb',
-            'Or build: cargo build --release --bin rfdb-server'
+            'Specify path: grafema server start --binary /path/to/rfdb-server',
+            'Or add to config.yaml:',
+            '  server:',
+            '    binaryPath: /path/to/rfdb-server',
+            'Or install: npm install @grafema/rfdb',
+            'Or build: cargo build --release && cp target/release/rfdb-server ~/.local/bin/'
         ]);
     }
     console.log(`Starting RFDB server...`);
+    console.log(`  Binary: ${binaryPath}`);
     console.log(`  Database: ${dbPath}`);
     console.log(`  Socket: ${socketPath}`);
     // Start server
@@ -152,16 +198,17 @@ serverCommand
     if (serverProcess.pid) {
         writeFileSync(pidPath, String(serverProcess.pid));
     }
-    // Wait for socket to appear
+    // Wait for socket to appear (increased timeout for slow systems)
     let attempts = 0;
-    while (!existsSync(socketPath) && attempts < 50) {
+    while (!existsSync(socketPath) && attempts < 100) {
         await sleep(100);
         attempts++;
     }
     if (!existsSync(socketPath)) {
         exitWithError('Server failed to start', [
             'Check if database path is valid',
-            'Check server logs for errors'
+            'Check server logs for errors',
+            `Binary used: ${binaryPath}`
         ]);
     }
     // Verify server is responsive

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grafema/cli",
-  "version": "0.2.1-beta",
+  "version": "0.2.3-beta",
   "description": "CLI for Grafema code analysis toolkit",
   "type": "module",
   "main": "./dist/cli.js",
@@ -37,8 +37,8 @@
     "ink-text-input": "^6.0.0",
     "react": "^19.2.3",
     "yaml": "^2.8.2",
-    "@grafema/core": "0.2.0-beta",
-    "@grafema/types": "0.2.0-beta"
+    "@grafema/core": "0.2.3-beta",
+    "@grafema/types": "0.2.1-beta"
   },
   "devDependencies": {
     "@types/node": "^25.0.8",

package/src/cli.ts

@@ -4,6 +4,9 @@
  */
 
 import { Command } from 'commander';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
 import { initCommand } from './commands/init.js';
 import { analyzeCommand } from './commands/analyze.js';
 import { overviewCommand } from './commands/overview.js';
@@ -22,12 +25,16 @@ import { doctorCommand } from './commands/doctor.js';
 import { schemaCommand } from './commands/schema.js';
 import { explainCommand } from './commands/explain.js';
 
+// Read version from package.json
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
+
 const program = new Command();
 
 program
   .name('grafema')
   .description('Grafema code analysis CLI')
-  .version('0.1.0-alpha.1');
+  .version(pkg.version);
 
 // Commands in logical order
 program.addCommand(initCommand);

package/src/commands/analyze.ts

@@ -189,6 +189,7 @@ export const analyzeCommand = new Command('analyze')
   .option('--debug', 'Enable debug mode (writes diagnostics.log)')
   .option('--log-level <level>', 'Set log level (silent, errors, warnings, info, debug)')
   .option('--strict', 'Enable strict mode (fail on unresolved references)')
+  .option('--auto-start', 'Auto-start RFDB server if not running')
   .addHelpText('after', `
 Examples:
   grafema analyze                Analyze current project
@@ -198,8 +199,11 @@ Examples:
   grafema analyze -v             Verbose output with progress details
   grafema analyze --debug        Write diagnostics.log for debugging
   grafema analyze --strict       Fail on unresolved references (debugging)
+  grafema analyze --auto-start   Auto-start server (useful for CI)
+
+Note: Start the server first with: grafema server start
 `)
-  .action(async (path: string, options: { service?: string; entrypoint?: string; clear?: boolean; quiet?: boolean; verbose?: boolean; debug?: boolean; logLevel?: string; strict?: boolean }) => {
+  .action(async (path: string, options: { service?: string; entrypoint?: string; clear?: boolean; quiet?: boolean; verbose?: boolean; debug?: boolean; logLevel?: string; strict?: boolean; autoStart?: boolean }) => {
     const projectPath = resolve(path);
     const grafemaDir = join(projectPath, '.grafema');
     const dbPath = join(grafemaDir, 'graph.rfdb');
@@ -216,8 +220,31 @@ Examples:
 
     log(`Analyzing project: ${projectPath}`);
 
-    const backend = new RFDBServerBackend({ dbPath });
-    await backend.connect();
+    // Connect to RFDB server
+    // Default: require explicit `grafema server start`
+    // Use --auto-start for CI or backwards compatibility
+    const backend = new RFDBServerBackend({
+      dbPath,
+      autoStart: options.autoStart ?? false
+    });
+
+    try {
+      await backend.connect();
+    } catch (err) {
+      if (!options.autoStart && err instanceof Error && err.message.includes('not running')) {
+        console.error('');
+        console.error('RFDB server is not running.');
+        console.error('');
+        console.error('Start the server first:');
+        console.error('  grafema server start');
+        console.error('');
+        console.error('Or use --auto-start flag:');
+        console.error('  grafema analyze --auto-start');
+        console.error('');
+        process.exit(1);
+      }
+      throw err;
+    }
 
     if (options.clear) {
       log('Clearing existing database...');

package/src/commands/server.ts

@@ -13,20 +13,49 @@ import { existsSync, unlinkSync, writeFileSync, readFileSync } from 'fs';
 import { spawn } from 'child_process';
 import { fileURLToPath } from 'url';
 import { setTimeout as sleep } from 'timers/promises';
-import { RFDBClient } from '@grafema/core';
+import { RFDBClient, loadConfig } from '@grafema/core';
 import { exitWithError } from '../utils/errorFormatter.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
+// Extend config type for server settings
+interface ServerConfig {
+  binaryPath?: string;
+}
+
 /**
  * Find RFDB server binary in order of preference:
- * 1. @grafema/rfdb npm package
- * 2. packages/rfdb-server/target/release (monorepo development)
- * 3. packages/rfdb-server/target/debug
+ * 1. Explicit path (from --binary flag or config)
+ * 2. Monorepo development (target/release, target/debug)
+ * 3. @grafema/rfdb npm package (prebuilt binaries)
+ * 4. ~/.local/bin/rfdb-server (user-installed)
  */
-function findServerBinary(): string | null {
-  // 1. Check @grafema/rfdb npm package
+function findServerBinary(explicitPath?: string): string | null {
+  // 1. Explicit path from --binary flag or config
+  if (explicitPath) {
+    const resolved = resolve(explicitPath);
+    if (existsSync(resolved)) {
+      return resolved;
+    }
+    // Explicit path specified but not found - this is an error
+    console.error(`Specified binary not found: ${resolved}`);
+    return null;
+  }
+
+  // 2. Check packages/rfdb-server in monorepo (for development)
+  const projectRoot = join(__dirname, '../../../..');
+  const releaseBinary = join(projectRoot, 'packages/rfdb-server/target/release/rfdb-server');
+  if (existsSync(releaseBinary)) {
+    return releaseBinary;
+  }
+
+  const debugBinary = join(projectRoot, 'packages/rfdb-server/target/debug/rfdb-server');
+  if (existsSync(debugBinary)) {
+    return debugBinary;
+  }
+
+  // 3. Check @grafema/rfdb npm package
   try {
     const rfdbPkg = require.resolve('@grafema/rfdb');
     const rfdbDir = dirname(rfdbPkg);
@@ -50,18 +79,10 @@ function findServerBinary(): string | null {
     // @grafema/rfdb not installed
   }
 
-  // 2. Check packages/rfdb-server in monorepo
-  // From packages/cli/dist/commands -> project root is 4 levels up
-  const projectRoot = join(__dirname, '../../../..');
-  const releaseBinary = join(projectRoot, 'packages/rfdb-server/target/release/rfdb-server');
-  if (existsSync(releaseBinary)) {
-    return releaseBinary;
-  }
-
-  // 3. Check debug build
-  const debugBinary = join(projectRoot, 'packages/rfdb-server/target/debug/rfdb-server');
-  if (existsSync(debugBinary)) {
-    return debugBinary;
+  // 4. Check ~/.local/bin (user-installed binary for unsupported platforms)
+  const homeBinary = join(process.env.HOME || '', '.local', 'bin', 'rfdb-server');
+  if (existsSync(homeBinary)) {
+    return homeBinary;
   }
 
   return null;
@@ -106,10 +127,15 @@ export const serverCommand = new Command('server')
   .description('Manage RFDB server lifecycle')
   .addHelpText('after', `
 Examples:
-  grafema server start           Start the RFDB server (detached)
-  grafema server stop            Stop the running server
-  grafema server status          Check if server is running
-  grafema server status --json   Server status as JSON
+  grafema server start                       Start the RFDB server
+  grafema server start --binary /path/to/bin Start with specific binary
+  grafema server stop                        Stop the running server
+  grafema server status                      Check if server is running
+  grafema server status --json               Server status as JSON
+
+Config (in .grafema/config.yaml):
+  server:
+    binaryPath: /path/to/rfdb-server    # Optional: path to binary
 `);
 
 // grafema server start
@@ -117,7 +143,8 @@ serverCommand
   .command('start')
   .description('Start the RFDB server')
   .option('-p, --project <path>', 'Project path', '.')
-  .action(async (options: { project: string }) => {
+  .option('-b, --binary <path>', 'Path to rfdb-server binary')
+  .action(async (options: { project: string; binary?: string }) => {
     const projectPath = resolve(options.project);
     const { grafemaDir, socketPath, dbPath, pidPath } = getProjectPaths(projectPath);
 
@@ -144,16 +171,43 @@ serverCommand
       unlinkSync(socketPath);
     }
 
-    // Find server binary
-    const binaryPath = findServerBinary();
+    // Determine binary path: CLI flag > config > auto-detect
+    let binaryPath: string | null = null;
+
+    if (options.binary) {
+      // Explicit --binary flag
+      binaryPath = findServerBinary(options.binary);
+    } else {
+      // Try to read from config
+      try {
+        const config = loadConfig(projectPath);
+        const serverConfig = (config as unknown as { server?: ServerConfig }).server;
+        if (serverConfig?.binaryPath) {
+          binaryPath = findServerBinary(serverConfig.binaryPath);
+        }
+      } catch {
+        // Config not found or invalid - continue with auto-detect
+      }
+
+      // Auto-detect if not specified
+      if (!binaryPath) {
+        binaryPath = findServerBinary();
+      }
+    }
+
     if (!binaryPath) {
       exitWithError('RFDB server binary not found', [
-        'Install: npm install @grafema/rfdb',
-        'Or build: cargo build --release --bin rfdb-server'
+        'Specify path: grafema server start --binary /path/to/rfdb-server',
+        'Or add to config.yaml:',
+        '  server:',
+        '    binaryPath: /path/to/rfdb-server',
+        'Or install: npm install @grafema/rfdb',
+        'Or build: cargo build --release && cp target/release/rfdb-server ~/.local/bin/'
       ]);
     }
 
     console.log(`Starting RFDB server...`);
+    console.log(`  Binary: ${binaryPath}`);
     console.log(`  Database: ${dbPath}`);
     console.log(`  Socket: ${socketPath}`);
 
@@ -171,9 +225,9 @@ serverCommand
       writeFileSync(pidPath, String(serverProcess.pid));
     }
 
-    // Wait for socket to appear
+    // Wait for socket to appear (increased timeout for slow systems)
     let attempts = 0;
-    while (!existsSync(socketPath) && attempts < 50) {
+    while (!existsSync(socketPath) && attempts < 100) {
       await sleep(100);
       attempts++;
     }
@@ -181,7 +235,8 @@ serverCommand
     if (!existsSync(socketPath)) {
       exitWithError('Server failed to start', [
         'Check if database path is valid',
-        'Check server logs for errors'
+        'Check server logs for errors',
+        `Binary used: ${binaryPath}`
       ]);
     }