@grafema/cli 0.1.1-alpha → 0.2.1-beta

package/src/commands/init.ts

@@ -5,10 +5,15 @@
 import { Command } from 'commander';
 import { resolve, join } from 'path';
 import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
+import { spawn } from 'child_process';
+import { createInterface } from 'readline';
+import { fileURLToPath } from 'url';
 import { exitWithError } from '../utils/errorFormatter.js';
 import { stringify as stringifyYAML } from 'yaml';
 import { DEFAULT_CONFIG } from '@grafema/core';
 
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+
 /**
  * Generate config.yaml content with commented future features.
  * Only includes implemented features (plugins).
@@ -30,26 +35,90 @@ function generateConfigYAML(): string {
 # Documentation: https://github.com/grafema/grafema#configuration
 
 ${yaml}
-# Future: File discovery patterns (not yet implemented)
-# Grafema currently uses entrypoint-based discovery (follows imports from package.json main field)
-# Glob-based include/exclude patterns will be added in a future release
+# File filtering patterns (optional)
+# By default, Grafema follows imports from package.json entry points.
+# Use these patterns to control which files are analyzed:
 #
-# include:
+# include:  # Only analyze files matching these patterns
 #   - "src/**/*.{ts,js,tsx,jsx}"
-# exclude:
+#
+# exclude:  # Skip files matching these patterns (takes precedence over include)
 #   - "**/*.test.ts"
-#   - "node_modules/**"
+#   - "**/__tests__/**"
+#   - "**/node_modules/**"
 `;
 }
 
+/**
+ * Ask user a yes/no question. Returns true for yes (default), false for no.
+ */
+function askYesNo(question: string): Promise<boolean> {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      // Default yes (empty answer or 'y' or 'yes')
+      const normalized = answer.toLowerCase().trim();
+      resolve(normalized !== 'n' && normalized !== 'no');
+    });
+  });
+}
+
+/**
+ * Run grafema analyze in the given project path.
+ * Returns the exit code of the analyze process.
+ */
+function runAnalyze(projectPath: string): Promise<number> {
+  return new Promise((resolve) => {
+    const cliPath = join(__dirname, '..', 'cli.js');
+    const child = spawn('node', [cliPath, 'analyze', projectPath], {
+      stdio: 'inherit', // Pass through all I/O for user to see progress
+    });
+    child.on('close', (code) => resolve(code ?? 1));
+    child.on('error', () => resolve(1));
+  });
+}
+
+/**
+ * Print next steps after init.
+ */
+function printNextSteps(): void {
+  console.log('');
+  console.log('Next steps:');
+  console.log('  1. Review config:  code .grafema/config.yaml');
+  console.log('  2. Build graph:    grafema analyze');
+  console.log('  3. Explore:        grafema overview');
+}
+
+/**
+ * Check if running in interactive mode.
+ * Interactive if stdin is TTY and --yes flag not provided.
+ */
+function isInteractive(options: InitOptions): boolean {
+  return options.yes !== true && process.stdin.isTTY === true;
+}
+
 interface InitOptions {
   force?: boolean;
+  yes?: boolean;
 }
 
 export const initCommand = new Command('init')
   .description('Initialize Grafema in current project')
   .argument('[path]', 'Project path', '.')
   .option('-f, --force', 'Overwrite existing config')
+  .option('-y, --yes', 'Skip prompts (non-interactive mode)')
+  .addHelpText('after', `
+Examples:
+  grafema init                   Initialize in current directory
+  grafema init ./my-project      Initialize in specific directory
+  grafema init --force           Overwrite existing configuration
+  grafema init --yes             Skip prompts, auto-run analyze
+`)
   .action(async (path: string, options: InitOptions) => {
     const projectPath = resolve(path);
     const grafemaDir = join(projectPath, '.grafema');
@@ -59,10 +128,15 @@ export const initCommand = new Command('init')
 
     // Check package.json
     if (!existsSync(packageJsonPath)) {
-      exitWithError('No package.json found', [
-        'Initialize a project: npm init',
-        'Or check you are in the right directory'
-      ]);
+      console.error('✗ Grafema currently supports JavaScript/TypeScript projects only.');
+      console.error(`  No package.json found in ${projectPath}`);
+      console.error('');
+      console.error('  Supported: Node.js, React, Express, Next.js, Vue, Angular, etc.');
+      console.error('  Coming soon: Python, Go, Rust');
+      console.error('');
+      console.error('  If this IS a JS/TS project, create package.json first:');
+      console.error('    npm init -y');
+      process.exit(1);
     }
     console.log('✓ Found package.json');
 
@@ -79,8 +153,7 @@ export const initCommand = new Command('init')
       console.log('');
       console.log('✓ Grafema already initialized');
       console.log('  → Use --force to overwrite config');
-      console.log('');
-      console.log('Next: Run "grafema analyze" to build the code graph');
+      printNextSteps();
       return;
     }
 
@@ -107,6 +180,20 @@ export const initCommand = new Command('init')
       }
     }
 
-    console.log('');
-    console.log('Next: Run "grafema analyze" to build the code graph');
+    printNextSteps();
+
+    // Prompt to run analyze in interactive mode
+    if (isInteractive(options)) {
+      console.log('');
+      const runNow = await askYesNo('Run analysis now? [Y/n] ');
+      if (runNow) {
+        console.log('');
+        console.log('Starting analysis...');
+        console.log('');
+        const exitCode = await runAnalyze(projectPath);
+        if (exitCode !== 0) {
+          process.exit(exitCode);
+        }
+      }
+    }
   });

package/src/commands/ls.ts

@@ -0,0 +1,166 @@
+/**
+ * List command - List nodes by type
+ *
+ * Unix-style listing of nodes in the graph. Similar to `ls` for files,
+ * but for code graph nodes.
+ *
+ * Use cases:
+ * - "Show me all HTTP routes in this project"
+ * - "List all functions" (with limit for large codebases)
+ * - "What Socket.IO events are defined?"
+ */
+
+import { Command } from 'commander';
+import { resolve, join, relative } from 'path';
+import { existsSync } from 'fs';
+import { RFDBServerBackend } from '@grafema/core';
+import { exitWithError } from '../utils/errorFormatter.js';
+
+interface LsOptions {
+  project: string;
+  type: string;
+  json?: boolean;
+  limit: string;
+}
+
+interface NodeInfo {
+  id: string;
+  type: string;
+  name: string;
+  file: string;
+  line?: number;
+  method?: string;
+  path?: string;
+  url?: string;
+  event?: string;
+  [key: string]: unknown;
+}
+
+export const lsCommand = new Command('ls')
+  .description('List nodes by type')
+  .requiredOption('-t, --type <nodeType>', 'Node type to list (required)')
+  .option('-p, --project <path>', 'Project path', '.')
+  .option('-j, --json', 'Output as JSON')
+  .option('-l, --limit <n>', 'Limit results (default: 50)', '50')
+  .addHelpText('after', `
+Examples:
+  grafema ls --type FUNCTION              List functions (up to 50)
+  grafema ls --type http:route            List all HTTP routes
+  grafema ls --type http:request          List all HTTP requests (fetch/axios)
+  grafema ls -t socketio:event            List Socket.IO events
+  grafema ls --type CLASS -l 100          List up to 100 classes
+  grafema ls --type jsx:component --json  Output as JSON
+
+Discover available types:
+  grafema types                           List all types with counts
+`)
+  .action(async (options: LsOptions) => {
+    const projectPath = resolve(options.project);
+    const grafemaDir = join(projectPath, '.grafema');
+    const dbPath = join(grafemaDir, 'graph.rfdb');
+
+    if (!existsSync(dbPath)) {
+      exitWithError('No graph database found', ['Run: grafema analyze']);
+    }
+
+    const backend = new RFDBServerBackend({ dbPath });
+    await backend.connect();
+
+    try {
+      const limit = parseInt(options.limit, 10);
+      const nodeType = options.type;
+
+      // Check if type exists in graph
+      const typeCounts = await backend.countNodesByType();
+      if (!typeCounts[nodeType]) {
+        const availableTypes = Object.keys(typeCounts).sort();
+        exitWithError(`No nodes of type "${nodeType}" found`, [
+          'Available types:',
+          ...availableTypes.slice(0, 10).map(t => `  ${t}`),
+          availableTypes.length > 10 ? `  ... and ${availableTypes.length - 10} more` : '',
+          '',
+          'Run: grafema types    to see all types with counts',
+        ].filter(Boolean));
+      }
+
+      // Collect nodes
+      const nodes: NodeInfo[] = [];
+      for await (const node of backend.queryNodes({ nodeType: nodeType as any })) {
+        nodes.push({
+          id: node.id,
+          type: node.type || nodeType,
+          name: node.name || '',
+          file: node.file || '',
+          line: node.line,
+          method: node.method as string | undefined,
+          path: node.path as string | undefined,
+          url: node.url as string | undefined,
+          event: node.event as string | undefined,
+        });
+        if (nodes.length >= limit) break;
+      }
+
+      const totalCount = typeCounts[nodeType];
+      const showing = nodes.length;
+
+      if (options.json) {
+        console.log(JSON.stringify({
+          type: nodeType,
+          nodes,
+          showing,
+          total: totalCount,
+        }, null, 2));
+      } else {
+        console.log(`[${nodeType}] (${showing}${showing < totalCount ? ` of ${totalCount}` : ''}):`);
+        console.log('');
+
+        for (const node of nodes) {
+          const display = formatNodeForList(node, nodeType, projectPath);
+          console.log(`  ${display}`);
+        }
+
+        if (showing < totalCount) {
+          console.log('');
+          console.log(`  ... ${totalCount - showing} more. Use --limit ${totalCount} to see all.`);
+        }
+      }
+    } finally {
+      await backend.close();
+    }
+  });
+
+/**
+ * Format a node for list display based on its type.
+ * Different types show different fields.
+ */
+function formatNodeForList(node: NodeInfo, nodeType: string, projectPath: string): string {
+  const relFile = node.file ? relative(projectPath, node.file) : '';
+  const loc = node.line ? `${relFile}:${node.line}` : relFile;
+
+  // HTTP routes: METHOD PATH (location)
+  if (nodeType === 'http:route' && node.method && node.path) {
+    return `${node.method.padEnd(6)} ${node.path}  (${loc})`;
+  }
+
+  // HTTP requests: METHOD URL (location)
+  if (nodeType === 'http:request') {
+    const method = (node.method || 'GET').padEnd(6);
+    const url = node.url || 'dynamic';
+    return `${method} ${url}  (${loc})`;
+  }
+
+  // Socket.IO events: event_name
+  if (nodeType === 'socketio:event') {
+    return node.name || node.id;
+  }
+
+  // Socket.IO emit/on: event (location)
+  if (nodeType === 'socketio:emit' || nodeType === 'socketio:on') {
+    const event = node.event || node.name || 'unknown';
+    return `${event}  (${loc})`;
+  }
+
+  // Default: name (location)
+  const name = node.name || node.id;
+  return loc ? `${name}  (${loc})` : name;
+}

package/src/commands/overview.ts

@@ -17,6 +17,12 @@ export const overviewCommand = new Command('overview')
   .description('Show project overview and statistics')
   .option('-p, --project <path>', 'Project path', '.')
   .option('-j, --json', 'Output as JSON')
+  .addHelpText('after', `
+Examples:
+  grafema overview               Show project dashboard
+  grafema overview --json        Output statistics as JSON
+  grafema overview -p ./app      Overview for specific project
+`)
   .action(async (options: { project: string; json?: boolean }) => {
     const projectPath = resolve(options.project);
     const grafemaDir = join(projectPath, '.grafema');
@@ -61,20 +67,27 @@ export const overviewCommand = new Command('overview')
       console.log('External Interactions:');
       const httpRoutes = stats.nodesByType['http:route'] || 0;
       const dbQueries = stats.nodesByType['db:query'] || 0;
+      const socketEvents = stats.nodesByType['socketio:event'] || 0;
       const socketEmit = stats.nodesByType['socketio:emit'] || 0;
       const socketOn = stats.nodesByType['socketio:on'] || 0;
       const events = stats.nodesByType['event:listener'] || 0;
 
       if (httpRoutes > 0) console.log(`├─ HTTP routes: ${httpRoutes}`);
       if (dbQueries > 0) console.log(`├─ Database queries: ${dbQueries}`);
-      if (socketEmit + socketOn > 0) console.log(`├─ Socket.IO: ${socketEmit} emit, ${socketOn} listeners`);
+      if (socketEvents > 0) {
+        // New format showing event count prominently
+        console.log(`├─ Socket.IO: ${socketEvents} events (${socketEmit} emit, ${socketOn} listeners)`);
+      } else if (socketEmit + socketOn > 0) {
+        // Fallback for graphs analyzed before REG-209
+        console.log(`├─ Socket.IO: ${socketEmit} emit, ${socketOn} listeners`);
+      }
       if (events > 0) console.log(`├─ Event listeners: ${events}`);
 
       // Check for external module refs
       const externalModules = stats.nodesByType['EXTERNAL_MODULE'] || 0;
       if (externalModules > 0) console.log(`└─ External modules: ${externalModules}`);
 
-      if (httpRoutes + dbQueries + socketEmit + socketOn + events + externalModules === 0) {
+      if (httpRoutes + dbQueries + socketEvents + socketEmit + socketOn + events + externalModules === 0) {
         console.log('└─ (none detected)');
       }
       console.log('');