@grafema/cli 0.3.24 → 0.3.27

package/dist/commands/upgrade.js

@@ -0,0 +1,279 @@
+import { Command } from 'commander';
+import { existsSync, readdirSync, lstatSync, unlinkSync, rmSync, statSync, mkdirSync, } from 'fs';
+import { join, resolve } from 'path';
+import { getGrafemaBinDir, DOWNLOADABLE_BINARIES, isBinaryCurrentVersion, downloadBinary, GRAFEMA_VERSION, } from '@grafema/util';
+const COLORS = {
+    green: '\x1b[32m',
+    red: '\x1b[31m',
+    yellow: '\x1b[33m',
+    cyan: '\x1b[36m',
+    dim: '\x1b[2m',
+    bold: '\x1b[1m',
+    reset: '\x1b[0m',
+};
+const LANG_BINARIES = {
+    js: ['grafema-analyzer', 'grafema-resolve'],
+    python: ['grafema-python-analyzer', 'python-resolve'],
+    haskell: ['haskell-analyzer', 'haskell-resolve'],
+    rust: ['grafema-rust-resolve'],
+    java: ['grafema-java-analyzer', 'java-resolve', 'java-parser'],
+    kotlin: ['grafema-kotlin-analyzer', 'kotlin-resolve', 'kotlin-parser'],
+    go: ['grafema-go-analyzer', 'go-resolve', 'go-parser'],
+    cpp: ['grafema-cpp-analyzer', 'cpp-resolve'],
+    swift: ['grafema-swift-analyzer', 'swift-resolve', 'swift-parser'],
+    objc: ['grafema-objc-analyzer', 'objc-parser'],
+    beam: ['beam-analyzer', 'beam-resolve'],
+};
+const INFRASTRUCTURE = ['grafema-orchestrator', 'rfdb-server'];
+const DOWNLOADABLE_SET = new Set(DOWNLOADABLE_BINARIES);
+function formatBytes(bytes) {
+    if (bytes === 0)
+        return '0 B';
+    const units = ['B', 'KB', 'MB', 'GB'];
+    const i = Math.min(Math.floor(Math.log(bytes) / Math.log(1024)), units.length - 1);
+    const val = bytes / Math.pow(1024, i);
+    return `${val.toFixed(i === 0 ? 0 : 1)} ${units[i]}`;
+}
+function auditBinDir(binDir) {
+    const toClean = [];
+    const knownBinaries = [];
+    if (!existsSync(binDir))
+        return { toClean, knownBinaries };
+    for (const entry of readdirSync(binDir)) {
+        const fullPath = join(binDir, entry);
+        let stat;
+        try {
+            stat = lstatSync(fullPath);
+        }
+        catch {
+            continue;
+        }
+        if (stat.isSymbolicLink() && !existsSync(fullPath)) {
+            toClean.push({ path: fullPath, name: entry, reason: 'broken symlink', size: 0 });
+            continue;
+        }
+        if (entry.startsWith('.build-hash.') || entry.endsWith('.downloading')) {
+            toClean.push({ path: fullPath, name: entry, reason: 'dev artifact', size: stat.size });
+            continue;
+        }
+        if (entry.endsWith('.version')) {
+            const binaryName = entry.slice(0, -'.version'.length);
+            if (!existsSync(join(binDir, binaryName))) {
+                toClean.push({ path: fullPath, name: entry, reason: 'orphaned version file', size: stat.size });
+            }
+            continue;
+        }
+        if (entry === '.gitkeep')
+            continue;
+        if (DOWNLOADABLE_SET.has(entry)) {
+            knownBinaries.push(entry);
+        }
+        else {
+            toClean.push({ path: fullPath, name: entry, reason: 'unknown binary', size: stat.size });
+        }
+    }
+    return { toClean, knownBinaries };
+}
+function getTargetBinaries(options, existingBinaries) {
+    if (options.all) {
+        return [...DOWNLOADABLE_BINARIES];
+    }
+    if (options.lang) {
+        const langs = options.lang.split(',').map(l => l.trim().toLowerCase());
+        const invalid = langs.filter(l => !LANG_BINARIES[l]);
+        if (invalid.length > 0) {
+            console.error(`${COLORS.red}Unknown languages: ${invalid.join(', ')}${COLORS.reset}`);
+            console.error(`Available: ${Object.keys(LANG_BINARIES).join(', ')}`);
+            process.exit(1);
+        }
+        const bins = new Set(INFRASTRUCTURE);
+        for (const lang of langs) {
+            for (const b of LANG_BINARIES[lang])
+                bins.add(b);
+        }
+        return [...bins];
+    }
+    const set = new Set(existingBinaries);
+    for (const b of INFRASTRUCTURE)
+        set.add(b);
+    return [...set];
+}
+function auditProjectDir(projectPath) {
+    const grafemaDir = join(projectPath, '.grafema');
+    if (!existsSync(grafemaDir))
+        return [];
+    const toClean = [];
+    const diagLog = join(grafemaDir, 'diagnostics.log');
+    if (existsSync(diagLog)) {
+        toClean.push({ path: diagLog, name: 'diagnostics.log', reason: 'old diagnostics', size: statSync(diagLog).size });
+    }
+    const oldDb = join(grafemaDir, 'grafema.rfdb');
+    const newDb = join(grafemaDir, 'graph.rfdb');
+    if (existsSync(oldDb) && existsSync(newDb)) {
+        let size = 0;
+        try {
+            for (const f of readdirSync(oldDb)) {
+                try {
+                    size += statSync(join(oldDb, f)).size;
+                }
+                catch { /* skip */ }
+            }
+        }
+        catch { /* skip */ }
+        toClean.push({ path: oldDb, name: 'grafema.rfdb/', reason: 'stale database (renamed to graph.rfdb)', size });
+    }
+    const logsDir = join(grafemaDir, 'logs');
+    if (existsSync(logsDir)) {
+        const thirtyDaysAgo = Date.now() - 30 * 24 * 60 * 60 * 1000;
+        try {
+            for (const f of readdirSync(logsDir)) {
+                const fp = join(logsDir, f);
+                try {
+                    const s = statSync(fp);
+                    if (s.isFile() && s.mtimeMs < thirtyDaysAgo) {
+                        toClean.push({ path: fp, name: `logs/${f}`, reason: 'log older than 30 days', size: s.size });
+                    }
+                }
+                catch { /* skip */ }
+            }
+        }
+        catch { /* skip */ }
+    }
+    return toClean;
+}
+export const upgradeCommand = new Command('upgrade')
+    .description('Clean stale artifacts and upgrade binaries to current version')
+    .option('-a, --all', 'Download all available binaries (not just existing)')
+    .option('-l, --lang <langs>', 'Comma-separated languages to install (js,python,rust,...)')
+    .option('-n, --dry-run', 'Preview changes without executing')
+    .option('-p, --project [path]', 'Also clean project .grafema/ artifacts')
+    .addHelpText('after', `
+Examples:
+  grafema upgrade                  Clean + upgrade existing binaries
+  grafema upgrade --all            Clean + download ALL available binaries
+  grafema upgrade --lang js,python Clean + ensure JS and Python analyzers
+  grafema upgrade --dry-run        Preview what would be cleaned/upgraded
+  grafema upgrade --project        Also clean .grafema/ in current directory
+
+Available languages: ${Object.keys(LANG_BINARIES).join(', ')}`)
+    .action(async (options) => {
+    const dryRun = !!options.dryRun;
+    const prefix = dryRun ? `${COLORS.dim}[dry-run]${COLORS.reset} ` : '';
+    const binDir = getGrafemaBinDir();
+    console.log(`${COLORS.bold}Grafema Upgrade${COLORS.reset} ${COLORS.dim}v${GRAFEMA_VERSION}${COLORS.reset}`);
+    console.log();
+    if (!existsSync(binDir)) {
+        mkdirSync(binDir, { recursive: true });
+    }
+    // Phase 1+2: Audit and clean ~/.grafema/bin/
+    const { toClean, knownBinaries } = auditBinDir(binDir);
+    if (toClean.length > 0) {
+        console.log(`${COLORS.bold}Cleaning ~/.grafema/bin/${COLORS.reset}`);
+        for (const item of toClean) {
+            console.log(`  ${prefix}${COLORS.red}✗${COLORS.reset} ${item.name} ${COLORS.dim}(${item.reason}, ${formatBytes(item.size)})${COLORS.reset}`);
+            if (!dryRun) {
+                try {
+                    const s = lstatSync(item.path);
+                    if (s.isDirectory()) {
+                        rmSync(item.path, { recursive: true, force: true });
+                    }
+                    else {
+                        unlinkSync(item.path);
+                    }
+                }
+                catch (err) {
+                    console.log(`    ${COLORS.yellow}warning: ${err instanceof Error ? err.message : err}${COLORS.reset}`);
+                }
+            }
+        }
+        console.log();
+    }
+    // Phase 3: Upgrade binaries
+    const targets = getTargetBinaries(options, knownBinaries);
+    console.log(`${COLORS.bold}Upgrading binaries${COLORS.reset} ${COLORS.dim}(target: binaries-v${GRAFEMA_VERSION})${COLORS.reset}`);
+    let upgradedCount = 0;
+    let currentCount = 0;
+    let failedCount = 0;
+    for (const name of targets) {
+        const binaryPath = join(binDir, name);
+        if (existsSync(binaryPath) && isBinaryCurrentVersion(binaryPath)) {
+            currentCount++;
+            console.log(`  ${COLORS.green}✓${COLORS.reset} ${name} ${COLORS.dim}-- current${COLORS.reset}`);
+            continue;
+        }
+        if (dryRun) {
+            const status = existsSync(binaryPath) ? 'stale, would upgrade' : 'missing, would download';
+            console.log(`  ${prefix}${COLORS.cyan}↓${COLORS.reset} ${name} ${COLORS.dim}(${status})${COLORS.reset}`);
+            upgradedCount++;
+            continue;
+        }
+        try {
+            process.stdout.write(`  ${COLORS.cyan}↓${COLORS.reset} ${name} -- downloading...`);
+            const downloaded = await downloadBinary(name);
+            const size = statSync(downloaded).size;
+            process.stdout.write(`\r  ${COLORS.green}✓${COLORS.reset} ${name} ${COLORS.dim}(${formatBytes(size)})${COLORS.reset}          \n`);
+            upgradedCount++;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stdout.write(`\r  ${COLORS.red}✗${COLORS.reset} ${name} -- ${msg}          \n`);
+            failedCount++;
+        }
+    }
+    console.log();
+    // Phase 4: Project cleanup (optional)
+    let projectCleanedCount = 0;
+    let projectCleanedBytes = 0;
+    if (options.project !== undefined) {
+        const projectPath = typeof options.project === 'string' ? resolve(options.project) : resolve('.');
+        const projectActions = auditProjectDir(projectPath);
+        if (projectActions.length > 0) {
+            console.log(`${COLORS.bold}Cleaning project artifacts${COLORS.reset} ${COLORS.dim}(${projectPath}/.grafema/)${COLORS.reset}`);
+            for (const item of projectActions) {
+                console.log(`  ${prefix}${COLORS.red}✗${COLORS.reset} ${item.name} ${COLORS.dim}(${item.reason}, ${formatBytes(item.size)})${COLORS.reset}`);
+                if (!dryRun) {
+                    try {
+                        const s = lstatSync(item.path);
+                        if (s.isDirectory()) {
+                            rmSync(item.path, { recursive: true, force: true });
+                        }
+                        else {
+                            unlinkSync(item.path);
+                        }
+                        projectCleanedCount++;
+                        projectCleanedBytes += item.size;
+                    }
+                    catch (err) {
+                        console.log(`    ${COLORS.yellow}warning: ${err instanceof Error ? err.message : err}${COLORS.reset}`);
+                    }
+                }
+                else {
+                    projectCleanedCount++;
+                    projectCleanedBytes += item.size;
+                }
+            }
+            console.log();
+        }
+    }
+    // Summary
+    const parts = [];
+    if (toClean.length > 0) {
+        const totalCleaned = toClean.reduce((s, a) => s + a.size, 0);
+        parts.push(`cleaned ${toClean.length} files (${formatBytes(totalCleaned)})`);
+    }
+    if (upgradedCount > 0)
+        parts.push(`upgraded ${upgradedCount} binaries`);
+    if (currentCount > 0)
+        parts.push(`${currentCount} already current`);
+    if (failedCount > 0)
+        parts.push(`${COLORS.red}${failedCount} failed${COLORS.reset}`);
+    if (projectCleanedCount > 0)
+        parts.push(`project: ${projectCleanedCount} files (${formatBytes(projectCleanedBytes)})`);
+    if (parts.length === 0) {
+        console.log(`${COLORS.green}✓${COLORS.reset} Everything is up to date.`);
+    }
+    else {
+        console.log(`${COLORS.bold}Summary:${COLORS.reset} ${parts.join(', ')}`);
+    }
+});
+//# sourceMappingURL=upgrade.js.map

package/dist/commands/upgrade.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade.js","sourceRoot":"","sources":["../../src/commands/upgrade.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grafema/cli",
-  "version": "0.3.24",
+  "version": "0.3.27",
   "description": "CLI for Grafema code analysis toolkit",
   "type": "module",
   "main": "./dist/cli.js",
@@ -35,9 +35,9 @@
   "dependencies": {
     "commander": "^13.0.0",
     "yaml": "^2.8.2",
-    "@grafema/util": "0.3.24",
-    "@grafema/api": "0.3.24",
-    "@grafema/types": "0.3.24"
+    "@grafema/types": "0.3.27",
+    "@grafema/util": "0.3.27",
+    "@grafema/api": "0.3.27"
   },
   "optionalDependencies": {
     "@grafema/grafema-darwin-arm64": "0.3.16",

package/src/cli.ts

@@ -35,6 +35,10 @@ import { fileCommand } from './commands/file.js';
 import { setupSkillCommand } from './commands/setup-skill.js';
 import { gitIngestCommand } from './commands/git-ingest.js';
 import { registryCommand } from './commands/registry.js';
+import { featuresCommand } from './commands/features.js';
+import { exportCommand } from './commands/export.js';
+import { startCommand, stopCommand } from './commands/start.js';
+import { upgradeCommand } from './commands/upgrade.js';
 
 // Read version from package.json
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -53,6 +57,10 @@ program.addCommand(wtfCommand);
 program.addCommand(whoCommand);
 program.addCommand(whyCommand);
 
+// Lifecycle commands
+program.addCommand(startCommand);
+program.addCommand(stopCommand);
+
 // Commands in logical order
 program.addCommand(initCommand);
 program.addCommand(analyzeCommand);
@@ -72,11 +80,14 @@ program.addCommand(coverageCommand);
 program.addCommand(checkCommand);
 program.addCommand(serverCommand);
 program.addCommand(doctorCommand);
+program.addCommand(upgradeCommand);
 program.addCommand(schemaCommand);
 program.addCommand(explainCommand);
 program.addCommand(fileCommand);
 program.addCommand(setupSkillCommand);
 program.addCommand(gitIngestCommand);
 program.addCommand(registryCommand);
+program.addCommand(featuresCommand);
+program.addCommand(exportCommand);
 
 program.parse();

package/src/commands/analyzeAction.ts

@@ -20,9 +20,20 @@ import {
   ensureBinary,
   ManifestGenerator,
   ManifestResolver,
+  EffectsLookup,
   GRAFEMA_VERSION,
   getSchemaVersion,
 } from '@grafema/util';
+import { enrichBehaviors } from '@grafema/util/enrichers/behaviorEnricher';
+import { enrichContracts } from '@grafema/util/enrichers/contractEnricher';
+import { enrichLibraryCallbacks } from '@grafema/util/enrichers/libraryCallbackEnricher';
+import { enrichPackageApis } from '@grafema/util/enrichers/packageApiEnricher';
+import { enrichMcpToolDefinitions } from '@grafema/util/enrichers/mcpToolDefinitionEnricher';
+import { enrichSpecedContracts } from '@grafema/util/enrichers/specedContractEnricher';
+import { commanderExtractor } from '@grafema/util/enrichers/extractors/commanderExtractor';
+import { mcpInputSchemaExtractor } from '@grafema/util/enrichers/extractors/mcpInputSchemaExtractor';
+import { vscodeContributesExtractor } from '@grafema/util/enrichers/extractors/vscodeContributesExtractor';
+import { httpRouteExtractor } from '@grafema/util/enrichers/extractors/httpRouteExtractor';
 import type { LogLevel } from '@grafema/util';
 import { scanExtensions, generateSmartConfig, writeConfig, updateGitignore, formatDetected } from '../utils/quickstart.js';
 
@@ -95,8 +106,8 @@ const EXT_TO_BINARIES: Record<string, string[]> = {
   pyi: ['grafema-python-analyzer', 'python-resolve'],
   // Haskell
   hs: ['haskell-analyzer', 'haskell-resolve'],
-  // Rust
-  rs: ['grafema-rust-analyzer', 'grafema-rust-resolve'],
+  // Rust (analyzer is native in-process inside orchestrator)
+  rs: ['grafema-rust-resolve'],
   // Java
   java: ['grafema-java-analyzer', 'java-resolve', 'java-parser'],
   // Kotlin
@@ -322,6 +333,114 @@ export async function analyzeAction(path: string, options: { service?: string; e
       info(`  Nodes: ${stats.nodeCount}`);
       info(`  Edges: ${stats.edgeCount}`);
 
+      // Run library-callback enricher before manifest generation.
+      // Creates domain nodes (cli:command, mcp:tool, ...) and HANDLES edges
+      // for callbacks passed to library entry points (Commander, MCP SDK, ...).
+      // Reuses the effects-db loaded for ManifestGenerator.
+      const effectsDbPath = resolveEffectsDbPath(projectPath);
+      const effectsLookup = effectsDbPath
+        ? EffectsLookup.load(effectsDbPath)
+        : EffectsLookup.empty();
+      try {
+        // RFDBServerBackend's RFDBClient field is private at compile time but
+        // accessible at runtime; the enricher only needs the wire-level client.
+        const client = (backend as unknown as { client: Parameters<typeof enrichLibraryCallbacks>[0] }).client;
+        if (client) {
+          const result = await enrichLibraryCallbacks(client, effectsLookup);
+          info(`  Library callbacks: ${result.domainNodesCreated} domain nodes, ${result.handlesEdgesCreated} HANDLES edges (unresolved: ${result.unresolvedCalls})`);
+        }
+      } catch (err) {
+        debug(`Library callback enricher skipped: ${err instanceof Error ? err.message : String(err)}`);
+      }
+
+      // MCP tool definition enricher — scans `packages/mcp/src/definitions/*-tools.ts`
+      // (or any matching tree under projectPath) and creates `mcp:tool` nodes for
+      // each defined tool. Complements libraryCallbackEnricher: that one captures
+      // the high-level setRequestHandler calls; this one captures the ~30+ tools
+      // dispatched by the switch statement inside the CallTool handler.
+      try {
+        const client = (backend as unknown as { client: Parameters<typeof enrichMcpToolDefinitions>[0] }).client;
+        if (client) {
+          const definitionsDir = join(projectPath, 'packages/mcp/src/definitions');
+          const result = await enrichMcpToolDefinitions(client, { definitionsDir });
+          if (result.toolNodesCreated > 0) {
+            info(`  MCP tool defs: ${result.toolNodesCreated} mcp:tool nodes, ${result.handlesEdgesCreated} HANDLES edges (unresolved: ${result.unresolvedHandlers.length})`);
+          }
+        }
+      } catch (err) {
+        debug(`MCP tool definition enricher skipped: ${err instanceof Error ? err.message : String(err)}`);
+      }
+
+      // Contract enricher — for every FEATURE-class node (cli:command, mcp:tool,
+      // vscode:command) created by the L0 entry-point enrichers above, walk the
+      // HANDLES edge to the handler FUNCTION and extract a CONTRACT node carrying
+      // structured inputs/outputs/errors metadata. Must run AFTER the FEATURE
+      // creators (enrichLibraryCallbacks, enrichMcpToolDefinitions) so HANDLES
+      // edges already exist, and BEFORE generateManifest so contracts can flow
+      // into the manifest if needed.
+      try {
+        const client = (backend as unknown as { client: Parameters<typeof enrichContracts>[0] }).client;
+        if (client) {
+          const result = await enrichContracts(client);
+          info(`  Contracts: ${result.contractsCreated} contracts (${result.inputsTotal} inputs, ${result.outputsTotal} outputs, ${result.errorsTotal} errors); ${result.featuresWithoutEntry} features lacked HANDLES edge`);
+        }
+      } catch (err) {
+        debug(`Contract enricher skipped: ${err instanceof Error ? err.message : String(err)}`);
+      }
+
+      // Speced-contract enricher — for every FEATURE node, run the registered
+      // per-category extractors (commander spec strings, MCP inputSchema, …)
+      // to produce SPECED_CONTRACT nodes carrying the user-facing interface.
+      // Distinct from the existing CONTRACT (handler signature scrape) which
+      // is implementation-side. See `_ai/research/feature-taxonomy.md` §1.3.
+      try {
+        const client = (backend as unknown as { client: Parameters<typeof enrichSpecedContracts>[0] }).client;
+        if (client) {
+          const result = await enrichSpecedContracts(client, [
+            commanderExtractor,
+            mcpInputSchemaExtractor,
+            vscodeContributesExtractor,
+            httpRouteExtractor,
+          ]);
+          info(`  Speced contracts: ${result.contractsCreated} (${result.inputsTotal} inputs); byCategory=${JSON.stringify(result.byCategory)}; missingExtractor=${result.featuresWithoutExtractor}, missingSpec=${result.featuresWithoutSpec}`);
+        }
+      } catch (err) {
+        debug(`Speced contract enricher skipped: ${err instanceof Error ? err.message : String(err)}`);
+      }
+
+      // Behavior enricher — for every FEATURE-class node, walk the HANDLES
+      // edge to the entry function and compute a transitive CALLS closure.
+      // Stores BEHAVIOR with hash + effects + summary (no COMPRISES edges —
+      // see skill `materialize-only-what-queries-need`). Pass 2 emits
+      // SHARES_BEHAVIOR_WITH between behaviors with identical hash.
+      try {
+        const client = (backend as unknown as { client: Parameters<typeof enrichBehaviors>[0] }).client;
+        if (client) {
+          const result = await enrichBehaviors(client, effectsLookup);
+          info(`  Behaviors: ${result.behaviorsCreated} BEHAVIOR nodes, ${result.sharesBehaviorEdges} SHARES_BEHAVIOR_WITH edges (totalCoreNodes=${result.totalCoreNodes}, missingEntry=${result.featuresWithoutEntry})`);
+        }
+      } catch (err) {
+        debug(`Behavior enricher skipped: ${err instanceof Error ? err.message : String(err)}`);
+      }
+
+      // Package API enricher — for every monorepo package barrel
+      // (`packages/<pkg>/src/index.ts`), emit a `package:export` FEATURE node
+      // per EXPORT_BINDING and a HANDLES edge to the underlying definition.
+      // Surfaces inter-package public-API surfaces so the contract enricher
+      // (run already) can wire contracts onto these on the next pass; the
+      // benefit is realised by downstream consumers (manifest, GUI, agents).
+      try {
+        const client = (backend as unknown as { client: Parameters<typeof enrichPackageApis>[0] }).client;
+        if (client) {
+          const result = await enrichPackageApis(client);
+          if (result.apiNodesCreated > 0) {
+            info(`  Package APIs: ${result.apiNodesCreated} package:export nodes, ${result.handlesEdgesCreated} HANDLES edges across ${result.packagesScanned} barrels (unresolved: ${result.exportsWithoutHandler})`);
+          }
+        }
+      } catch (err) {
+        debug(`Package API enricher skipped: ${err instanceof Error ? err.message : String(err)}`);
+      }
+
       // Generate manifest after successful analysis
       try {
         const manifestPath = await generateManifest(backend, projectPath, grafemaDir, debug);
@@ -381,6 +500,20 @@ export async function analyzeAction(path: string, options: { service?: string; e
   }
 }
 
+/**
+ * Resolve effects-db directory: prefer the one shipped next to the CLI package,
+ * fall back to a project-local effects-db. Returns undefined if neither exists.
+ * Shared by both the library-callback enricher and ManifestGenerator.
+ */
+function resolveEffectsDbPath(projectPath: string): string | undefined {
+  const cliDir = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+  const candidates = [
+    join(cliDir, 'effects-db'),
+    join(projectPath, 'effects-db'),
+  ];
+  return candidates.find(p => existsSync(p));
+}
+
 /**
  * Generate manifest.yaml after successful analysis.
  * Reads package.json to determine package name and entry point,

package/src/commands/doctor/checks.ts

@@ -8,7 +8,7 @@
  * - Level 4: Informational - checkVersions
  */
 
-import { existsSync, readFileSync, statSync } from 'fs';
+import { existsSync, readFileSync, statSync, unlinkSync } from 'fs';
 import { join, dirname, delimiter } from 'path';
 import { fileURLToPath } from 'url';
 import { createRequire } from 'module';
@@ -261,11 +261,12 @@ export async function checkServerStatus(
       details: { version, socketPath },
     };
   } catch {
+    try { unlinkSync(socketPath); } catch { /* already gone */ }
     return {
       name: 'server',
       status: 'warn',
-      message: 'Server socket exists but not responding (stale)',
-      recommendation: 'Run: grafema analyze (will restart server)',
+      message: 'Stale socket removed. Run grafema analyze to restart server.',
+      recommendation: 'Run: grafema analyze (starts fresh server)',
     };
   }
 }

package/src/commands/explore.tsx

@@ -74,6 +74,7 @@ interface ExploreState {
   // Code preview
   showCodePreview: boolean;
   codePreviewLines: string[];
+  showHelp: boolean;
 }
 
 interface ExplorerProps {
@@ -108,6 +109,7 @@ function Explorer({ backend, startNode, projectPath }: ExplorerProps) {
     viewMode: 'function',
     showCodePreview: false,
     codePreviewLines: [],
+    showHelp: false,
   });
 
   // Load data when currentNode changes
@@ -214,7 +216,7 @@ function Explorer({ backend, startNode, projectPath }: ExplorerProps) {
     }
 
     if (input === '?') {
-      // TODO: show help
+      setState(s => ({ ...s, showHelp: !s.showHelp }))
       return;
     }
 
@@ -745,10 +747,35 @@ function Explorer({ backend, startNode, projectPath }: ExplorerProps) {
         </Box>
       )}
 
+      {/* Help overlay */}
+      {state.showHelp && (
+        <Box
+          flexDirection="column"
+          borderStyle="single"
+          borderColor="cyan"
+          paddingX={1}
+          marginBottom={1}
+        >
+          <Text bold color="cyan"> Клавиши управления </Text>
+          <Text>  q        — выход</Text>
+          <Text>  /        — поиск</Text>
+          <Text>  ?        — помощь (это окно)</Text>
+          <Text>  m        — переключить режим (модули/функции)</Text>
+          <Text>  Space    — предпросмотр кода</Text>
+          <Text>  ←/h      — callers / fields / sources</Text>
+          <Text>  →/l      — callees / methods / targets</Text>
+          <Text>  ↑/k      — предыдущий элемент</Text>
+          <Text>  ↓/j      — следующий элемент</Text>
+          <Text>  Enter    — перейти к узлу</Text>
+          <Text>  Bksp     — назад</Text>
+          <Text>  Tab      — toggle callers/callees</Text>
+        </Box>
+      )}
+
       {/* Help footer */}
       <Box marginTop={1} borderStyle="single" borderColor="gray" paddingX={1}>
         <Text color="gray">
-          ↑↓: Select | ←→: Panel | Enter: Open | Backspace: Back | /: Search | m: Modules | Space: Code | o: Editor | q: Quit
+          ↑↓: Select | ←→: Panel | Enter: Open | Backspace: Back | /: Search | m: Modules | Space: Code | o: Editor | ?: Help | q: Quit
         </Text>
       </Box>
     </Box>