fix(cli): add better-sqlite3 dependency and graceful error handling

- Add better-sqlite3 as direct dependency to fix native binding errors
- Add consistent error messages across dev activity, owners, map, stats
- Provide clear re-index instructions when data is missing
- Better UX for users upgrading to v0.8.0

Author: prosdev

.changeset/fix-sqlite-bindings-and-error-handling.md

@@ -0,0 +1,17 @@
+---
+"@lytics/dev-agent": patch
+"@lytics/dev-agent-cli": patch
+---
+
+## Bug Fix & UX Improvements
+
+### Fixed Native Bindings Error
+
+Added `better-sqlite3` as a direct dependency to fix "Could not locate the bindings file" error in globally installed package.
+
+### Improved Error Messages
+
+Added consistent, user-friendly error messages across all commands when indexed data is missing. Commands now provide clear re-index instructions instead of cryptic errors.
+
+Affected commands: `dev activity`, `dev owners`, `dev map`, `dev stats`
+

packages/cli/src/commands/activity.ts

@@ -131,7 +131,16 @@ export const activityCommand = new Command('activity')
       store.close();
 
       if (files.length === 0) {
-        logger.warn('No file metrics available.');
+        logger.warn('No activity metrics found.');
+        console.log('');
+        console.log(chalk.yellow('📌 This feature requires re-indexing your repository:'));
+        console.log('');
+        console.log(chalk.white('   dev index .'));
+        console.log('');
+        console.log(
+          chalk.dim('   This is a one-time operation. Future updates will maintain activity data.')
+        );
+        console.log('');
         process.exit(0);
       }
 

packages/cli/src/commands/map.ts

@@ -15,6 +15,7 @@ import {
   RepositoryIndexer,
 } from '@lytics/dev-agent-core';
 import { createLogger } from '@lytics/kero';
+import chalk from 'chalk';
 import { Command } from 'commander';
 import ora from 'ora';
 import { loadConfig } from '../utils/config.js';
@@ -100,9 +101,16 @@ Use Case:
       const stats = await indexer.getBasicStats();
       if (!stats || stats.filesScanned === 0) {
         spinner.fail('Repository not indexed');
-        logger.error('Run "dev index" first to index your repository');
         await indexer.close();
-        process.exit(1);
+        logger.warn('No indexed data found.');
+        console.log('');
+        console.log(chalk.yellow('📌 This command requires indexing your repository:'));
+        console.log('');
+        console.log(chalk.white('   dev index .'));
+        console.log('');
+        console.log(chalk.dim('   This is a one-time operation. Run in your repository root.'));
+        console.log('');
+        process.exit(0);
       }
 
       mapLogger.info(

packages/cli/src/commands/owners.ts

@@ -251,6 +251,23 @@ export const ownersCommand = new Command('owners')
       const allFiles = store.getCodeMetadata({ snapshotId: latestSnapshot.id, limit: 10000 });
       const totalFiles = allFiles.length;
 
+      // Check if file_authors data exists
+      const fileAuthors = store.getFileAuthors(latestSnapshot.id);
+      if (fileAuthors.size === 0) {
+        store.close();
+        logger.warn('No author contribution data found.');
+        console.log('');
+        console.log(chalk.yellow('📌 This feature requires re-indexing your repository:'));
+        console.log('');
+        console.log(chalk.white('   dev index .'));
+        console.log('');
+        console.log(
+          chalk.dim('   This is a one-time operation. Future updates will maintain author data.')
+        );
+        console.log('');
+        process.exit(0);
+      }
+
       const developers = calculateDeveloperOwnership(store, latestSnapshot.id, repositoryPath);
       store.close();
 

packages/cli/src/commands/stats.ts

@@ -158,9 +158,14 @@ What You'll See:
         spinner.stop();
 
         if (!stats) {
-          output.warn('No indexing statistics available');
-          output.log(`Run ${chalk.cyan('dev index')} to index your repository first`);
-          output.log('');
+          output.warn('No indexed data found.');
+          console.log('');
+          console.log(chalk.yellow('📌 This command requires indexing your repository:'));
+          console.log('');
+          console.log(chalk.white('   dev index .'));
+          console.log('');
+          console.log(chalk.dim('   This is a one-time operation. Run in your repository root.'));
+          console.log('');
           return;
         }
 

packages/dev-agent/package.json

@@ -45,6 +45,7 @@
   "dependencies": {
     "@lancedb/lancedb": "^0.22.3",
     "@xenova/transformers": "^2.17.2",
+    "better-sqlite3": "^12.5.0",
     "ts-morph": "^27.0.2",
     "web-tree-sitter": "^0.25.10"
   },