project-compass 1.0.10 → 2.0.0

package/src/cli.js

@@ -1,23 +1,28 @@
 #!/usr/bin/env node
 import React, {useCallback, useEffect, useMemo, useRef, useState} from 'react';
 import {render, Box, Text, useApp, useInput} from 'ink';
-import fastGlob from 'fast-glob';
 import path from 'path';
 import fs from 'fs';
-import os from 'os';
 import kleur from 'kleur';
 import {execa} from 'execa';
+import {discoverProjects, SCHEMA_GUIDE} from './projectDetection.js';
+import {CONFIG_PATH, PLUGIN_FILE, ensureConfigDir} from './configPaths.js';
 
 const create = React.createElement;
-const CONFIG_DIR = path.join(os.homedir(), '.project-compass');
-const CONFIG_PATH = path.join(CONFIG_DIR, 'config.json');
-const PLUGIN_FILE = path.join(CONFIG_DIR, 'plugins.json');
 const DEFAULT_CONFIG = {customCommands: {}};
-function ensureConfigDir() {
-  if (!fs.existsSync(CONFIG_DIR)) {
-    fs.mkdirSync(CONFIG_DIR, {recursive: true});
-  }
-}
+const ART_CHARS = ['▁', '▃', '▄', '▅', '▇'];
+const ART_COLORS = ['magenta', 'blue', 'cyan', 'yellow', 'red'];
+const OUTPUT_WINDOW_SIZE = 8;
+const OUTPUT_WINDOW_HEIGHT = OUTPUT_WINDOW_SIZE + 2;
+const PROJECTS_MIN_WIDTH = 32;
+const DETAILS_MIN_WIDTH = 44;
+const HELP_CARD_MIN_WIDTH = 28;
+const RECENT_RUN_LIMIT = 5;
+const ACTION_MAP = {
+  b: 'build',
+  t: 'test',
+  r: 'run'
+};
 
 function saveConfig(config) {
   try {
@@ -48,744 +53,6 @@ function loadConfig() {
   return {...DEFAULT_CONFIG};
 }
 
-function parseCommandTokens(value) {
-  if (Array.isArray(value)) {
-    return value.map((token) => String(token));
-  }
-  if (typeof value === 'string') {
-    return value.trim().split(/\s+/).filter(Boolean);
-  }
-  return [];
-}
-
-function resolveScriptCommand(project, scriptName, fallback = null) {
-  const scripts = project.metadata?.scripts || {};
-  if (Object.prototype.hasOwnProperty.call(scripts, scriptName)) {
-    return ['npm', 'run', scriptName];
-  }
-  if (typeof fallback === 'function') {
-    return fallback();
-  }
-  return fallback;
-}
-
-function gatherNodeDependencies(pkg) {
-  const deps = new Set();
-  ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'].forEach((key) => {
-    if (pkg[key]) {
-      Object.keys(pkg[key]).forEach((name) => deps.add(name));
-    }
-  });
-  return Array.from(deps);
-}
-
-function gatherPythonDependencies(projectPath) {
-  const set = new Set();
-  const addFromFile = (filePath) => {
-    if (!fs.existsSync(filePath)) {
-      return;
-    }
-    const raw = fs.readFileSync(filePath, 'utf-8');
-    raw.split(/\r?\n/).forEach((line) => {
-      const clean = line.trim().split('#')[0].trim();
-      if (clean) {
-        const token = clean.split(/[>=<=~!]/)[0].trim().toLowerCase();
-        if (token) {
-          set.add(token);
-        }
-      }
-    });
-  };
-  addFromFile(path.join(projectPath, 'requirements.txt'));
-  const pyproject = path.join(projectPath, 'pyproject.toml');
-  if (fs.existsSync(pyproject)) {
-    const content = fs.readFileSync(pyproject, 'utf-8').toLowerCase();
-    const matches = content.match(/\b[a-z0-9-_/]+\b/g);
-    (matches || []).forEach((match) => {
-      if (match) {
-        set.add(match);
-      }
-    });
-  }
-  return Array.from(set);
-}
-
-function dependencyMatches(project, needle) {
-  const dependencies = (project.metadata?.dependencies || []).map((dep) => dep.toLowerCase());
-  const target = needle.toLowerCase();
-  return dependencies.some((value) => value === target || value.startsWith(`${target}@`) || value.includes(`/${target}`));
-}
-
-function hasProjectFile(project, file) {
-  return fs.existsSync(path.join(project.path, file));
-}
-
-
-const builtInFrameworks = [
-  {
-    id: 'next',
-    name: 'Next.js',
-    icon: '🧭',
-    description: 'React + Next.js (SSR/SSG) apps',
-    languages: ['Node.js'],
-    priority: 115,
-    match(project) {
-      const hasNextConfig = fs.existsSync(path.join(project.path, 'next.config.js'));
-      return dependencyMatches(project, 'next') || hasNextConfig;
-    },
-    commands(project) {
-      const commands = {};
-      const add = (key, label, fallback) => {
-        const tokens = resolveScriptCommand(project, key, fallback);
-        if (tokens) {
-          commands[key] = {label, command: tokens, source: 'framework'};
-        }
-      };
-      const buildFallback = () => ['npx', 'next', 'build'];
-      const startFallback = () => ['npx', 'next', 'start'];
-      const devFallback = () => ['npx', 'next', 'dev'];
-      add('run', 'Next dev', devFallback);
-      add('build', 'Next build', buildFallback);
-      add('test', 'Next test', () => ['npm', 'run', 'test']);
-      add('start', 'Next start', startFallback);
-      return commands;
-    }
-  },
-  {
-    id: 'react',
-    name: 'React',
-    icon: '⚛️',
-    description: 'React apps (CRA, Vite React)',
-    languages: ['Node.js'],
-    priority: 112,
-    match(project) {
-      return dependencyMatches(project, 'react') && (dependencyMatches(project, 'react-scripts') || dependencyMatches(project, 'vite') || hasProjectFile(project, 'vite.config.js'));
-    },
-    commands(project) {
-      const commands = {};
-      const add = (key, label, fallback) => {
-        const tokens = resolveScriptCommand(project, key, fallback);
-        if (tokens) {
-          commands[key] = {label, command: tokens, source: 'framework'};
-        }
-      };
-      add('run', 'React dev', () => ['npm', 'run', 'dev']);
-      add('build', 'React build', () => ['npm', 'run', 'build']);
-      add('test', 'React test', () => ['npm', 'run', 'test']);
-      return commands;
-    }
-  },
-  {
-    id: 'vue',
-    name: 'Vue.js',
-    icon: '🟩',
-    description: 'Vue CLI or Vite + Vue apps',
-    languages: ['Node.js'],
-    priority: 111,
-    match(project) {
-      return dependencyMatches(project, 'vue') && (hasProjectFile(project, 'vue.config.js') || dependencyMatches(project, '@vue/cli-service') || dependencyMatches(project, 'vite'));
-    },
-    commands(project) {
-      const commands = {};
-      const add = (key, label, fallback) => {
-        const tokens = resolveScriptCommand(project, key, fallback);
-        if (tokens) {
-          commands[key] = {label, command: tokens, source: 'framework'};
-        }
-      };
-      add('run', 'Vue dev', () => ['npm', 'run', 'dev']);
-      add('build', 'Vue build', () => ['npm', 'run', 'build']);
-      add('test', 'Vue test', () => ['npm', 'run', 'test']);
-      return commands;
-    }
-  },
-  {
-    id: 'nest',
-    name: 'NestJS',
-    icon: '🛡️',
-    description: 'NestJS backend',
-    languages: ['Node.js'],
-    priority: 110,
-    match(project) {
-      return dependencyMatches(project, '@nestjs/cli') || dependencyMatches(project, '@nestjs/core');
-    },
-    commands(project) {
-      const commands = {};
-      const add = (key, label, fallback) => {
-        const tokens = resolveScriptCommand(project, key, fallback);
-        if (tokens) {
-          commands[key] = {label, command: tokens, source: 'framework'};
-        }
-      };
-      add('run', 'Nest dev', () => ['npm', 'run', 'start:dev']);
-      add('build', 'Nest build', () => ['npm', 'run', 'build']);
-      add('test', 'Nest test', () => ['npm', 'run', 'test']);
-      return commands;
-    }
-  },
-  {
-    id: 'angular',
-    name: 'Angular',
-    icon: '🅰️',
-    description: 'Angular CLI projects',
-    languages: ['Node.js'],
-    priority: 109,
-    match(project) {
-      return hasProjectFile(project, 'angular.json') || dependencyMatches(project, '@angular/cli');
-    },
-    commands(project) {
-      const commands = {};
-      const add = (key, label, fallback) => {
-        const tokens = resolveScriptCommand(project, key, fallback);
-        if (tokens) {
-          commands[key] = {label, command: tokens, source: 'framework'};
-        }
-      };
-      add('run', 'Angular serve', () => ['npm', 'run', 'start']);
-      add('build', 'Angular build', () => ['npm', 'run', 'build']);
-      add('test', 'Angular test', () => ['npm', 'run', 'test']);
-      return commands;
-    }
-  },
-  {
-    id: 'sveltekit',
-    name: 'SvelteKit',
-    icon: '🌀',
-    description: 'SvelteKit apps',
-    languages: ['Node.js'],
-    priority: 108,
-    match(project) {
-      return hasProjectFile(project, 'svelte.config.js') || dependencyMatches(project, '@sveltejs/kit');
-    },
-    commands(project) {
-      const commands = {};
-      const add = (key, label, fallback) => {
-        const tokens = resolveScriptCommand(project, key, fallback);
-        if (tokens) {
-          commands[key] = {label, command: tokens, source: 'framework'};
-        }
-      };
-      add('run', 'SvelteKit dev', () => ['npm', 'run', 'dev']);
-      add('build', 'SvelteKit build', () => ['npm', 'run', 'build']);
-      add('test', 'SvelteKit test', () => ['npm', 'run', 'test']);
-      add('preview', 'SvelteKit preview', () => ['npm', 'run', 'preview']);
-      return commands;
-    }
-  },
-  {
-    id: 'nuxt',
-    name: 'Nuxt',
-    icon: '🪄',
-    description: 'Nuxt.js / Vue SSR',
-    languages: ['Node.js'],
-    priority: 107,
-    match(project) {
-      return hasProjectFile(project, 'nuxt.config.js') || dependencyMatches(project, 'nuxt');
-    },
-    commands(project) {
-      const commands = {};
-      const add = (key, label, fallback) => {
-        const tokens = resolveScriptCommand(project, key, fallback);
-        if (tokens) {
-          commands[key] = {label, command: tokens, source: 'framework'};
-        }
-      };
-      add('run', 'Nuxt dev', () => ['npm', 'run', 'dev']);
-      add('build', 'Nuxt build', () => ['npm', 'run', 'build']);
-      add('start', 'Nuxt start', () => ['npm', 'run', 'start']);
-      return commands;
-    }
-  },
-  {
-    id: 'astro',
-    name: 'Astro',
-    icon: '✨',
-    description: 'Astro static sites',
-    languages: ['Node.js'],
-    priority: 106,
-    match(project) {
-      const matches = ['astro.config.mjs', 'astro.config.ts'].some((file) => hasProjectFile(project, file));
-      return matches || dependencyMatches(project, 'astro');
-    },
-    commands(project) {
-      const commands = {};
-      const add = (key, label, fallback) => {
-        const tokens = resolveScriptCommand(project, key, fallback);
-        if (tokens) {
-          commands[key] = {label, command: tokens, source: 'framework'};
-        }
-      };
-      add('run', 'Astro dev', () => ['npm', 'run', 'dev']);
-      add('build', 'Astro build', () => ['npm', 'run', 'build']);
-      add('preview', 'Astro preview', () => ['npm', 'run', 'preview']);
-      return commands;
-    }
-  },
-  {
-    id: 'django',
-    name: 'Django',
-    icon: '🌿',
-    description: 'Django web application',
-    languages: ['Python'],
-    priority: 110,
-    match(project) {
-      return dependencyMatches(project, 'django') || hasProjectFile(project, 'manage.py');
-    },
-    commands(project) {
-      const managePath = path.join(project.path, 'manage.py');
-      if (!fs.existsSync(managePath)) {
-        return {};
-      }
-      return {
-        run: {label: 'Django runserver', command: ['python', 'manage.py', 'runserver'], source: 'framework'},
-        test: {label: 'Django test', command: ['python', 'manage.py', 'test'], source: 'framework'},
-        migrate: {label: 'Django migrate', command: ['python', 'manage.py', 'migrate'], source: 'framework'}
-      };
-    }
-  },
-  {
-    id: 'flask',
-    name: 'Flask',
-    icon: '🍶',
-    description: 'Flask microservices',
-    languages: ['Python'],
-    priority: 105,
-    match(project) {
-      return dependencyMatches(project, 'flask') || hasProjectFile(project, 'app.py');
-    },
-    commands(project) {
-      const commands = {};
-      const entry = hasProjectFile(project, 'app.py') ? 'app.py' : 'main.py';
-      commands.run = {label: 'Flask app', command: ['python', entry], source: 'framework'};
-      commands.test = {label: 'Pytest', command: ['pytest'], source: 'framework'};
-      return commands;
-    }
-  },
-  {
-    id: 'fastapi',
-    name: 'FastAPI',
-    icon: '⚡',
-    description: 'FastAPI + Uvicorn',
-    languages: ['Python'],
-    priority: 105,
-    match(project) {
-      return dependencyMatches(project, 'fastapi');
-    },
-    commands(project) {
-      const entry = hasProjectFile(project, 'main.py') ? 'main.py' : 'app.py';
-      return {
-        run: {label: 'Uvicorn reload', command: ['uvicorn', `${entry.split('.')[0]}:app`, '--reload'], source: 'framework'},
-        test: {label: 'Pytest', command: ['pytest'], source: 'framework'}
-      };
-    }
-  },
-  {
-    id: 'spring',
-    name: 'Spring Boot',
-    icon: '🌱',
-    description: 'Spring Boot apps',
-    languages: ['Java'],
-    priority: 105,
-    match(project) {
-      return dependencyMatches(project, 'spring-boot-starter') || hasProjectFile(project, 'src/main/java');
-    },
-    commands(project) {
-      const hasMvnw = fs.existsSync(path.join(project.path, 'mvnw'));
-      const base = hasMvnw ? './mvnw' : 'mvn';
-      return {
-        run: {label: 'Spring Boot run', command: [base, 'spring-boot:run'], source: 'framework'},
-        build: {label: 'Maven package', command: [base, 'package'], source: 'framework'},
-        test: {label: 'Maven test', command: [base, 'test'], source: 'framework'}
-      };
-    }
-  }
-];
-function loadUserFrameworks() {
-  ensureConfigDir();
-  try {
-    if (!fs.existsSync(PLUGIN_FILE)) {
-      return [];
-    }
-    const payload = JSON.parse(fs.readFileSync(PLUGIN_FILE, 'utf-8') || '{}');
-    const plugins = payload.plugins || [];
-    return plugins.map((entry) => {
-      const normalizedId = entry.id || (entry.name ? entry.name.toLowerCase().replace(/\s+/g, '-') : `plugin-${Math.random().toString(36).slice(2, 8)}`);
-      const commands = {};
-      Object.entries(entry.commands || {}).forEach(([key, value]) => {
-        const command = parseCommandTokens(typeof value === 'object' ? value.command : value);
-        if (!command.length) {
-          return;
-        }
-        commands[key] = {
-          label: typeof value === 'object' ? value.label || key : key,
-          command,
-          source: 'plugin'
-        };
-      });
-      return {
-        id: normalizedId,
-        name: entry.name || normalizedId,
-        icon: entry.icon || '🧩',
-        description: entry.description || '',
-        languages: entry.languages || [],
-        files: entry.files || [],
-        dependencies: entry.dependencies || [],
-        scripts: entry.scripts || [],
-        priority: Number.isFinite(entry.priority) ? entry.priority : 70,
-        commands,
-        match: entry.match
-      };
-    })
-    .filter((plugin) => plugin.name && plugin.commands && Object.keys(plugin.commands).length);
-  } catch (error) {
-    console.error(`Failed to parse plugins.json: ${error.message}`);
-    return [];
-  }
-}
-
-let cachedFrameworkPlugins = null;
-
-function getFrameworkPlugins() {
-  if (cachedFrameworkPlugins) {
-    return cachedFrameworkPlugins;
-  }
-  cachedFrameworkPlugins = [...builtInFrameworks, ...loadUserFrameworks()];
-  return cachedFrameworkPlugins;
-}
-
-function matchesPlugin(project, plugin) {
-  if (plugin.languages && plugin.languages.length > 0 && !plugin.languages.includes(project.type)) {
-    return false;
-  }
-  if (plugin.files && plugin.files.length > 0) {
-    const hit = plugin.files.some((file) => fs.existsSync(path.join(project.path, file)));
-    if (!hit) {
-      return false;
-    }
-  }
-  if (plugin.dependencies && plugin.dependencies.length > 0) {
-    const hit = plugin.dependencies.some((dep) => dependencyMatches(project, dep));
-    if (!hit) {
-      return false;
-    }
-  }
-  if (plugin.scripts && plugin.scripts.length > 0) {
-    const scripts = project.metadata?.scripts || {};
-    const hit = plugin.scripts.some((name) => Object.prototype.hasOwnProperty.call(scripts, name));
-    if (!hit) {
-      return false;
-    }
-  }
-  if (typeof plugin.match === 'function') {
-    if (!plugin.match(project)) {
-      return false;
-    }
-  }
-  return true;
-}
-
-function applyFrameworkPlugins(project) {
-  const plugins = getFrameworkPlugins();
-  let commands = {...project.commands};
-  const frameworks = [];
-  let maxPriority = project.priority || 0;
-  for (const plugin of plugins) {
-    if (!matchesPlugin(project, plugin)) {
-      continue;
-    }
-    frameworks.push({id: plugin.id, name: plugin.name, icon: plugin.icon, description: plugin.description});
-    if (plugin.priority && plugin.priority > maxPriority) {
-      maxPriority = plugin.priority;
-    }
-    const pluginCommands = typeof plugin.commands === 'function' ? plugin.commands(project) : plugin.commands;
-    if (pluginCommands) {
-      Object.entries(pluginCommands).forEach(([key, command]) => {
-        if (!Array.isArray(command.command) || command.command.length === 0) {
-          return;
-        }
-        commands = {
-          ...commands,
-          [key]: {
-            ...command,
-            source: command.source || 'framework'
-          }
-        };
-      });
-    }
-  }
-  return {...project, commands, frameworks, priority: maxPriority};
-}
-
-const IGNORE_PATTERNS = ['**/node_modules/**', '**/.git/**', '**/dist/**', '**/build/**', '**/target/**'];
-
-const SCHEMAS = [
-  {
-    type: 'node',
-    label: 'Node.js',
-    icon: '🟢',
-    priority: 90,
-    files: ['package.json'],
-    async build(projectPath, manifest) {
-      const pkgPath = path.join(projectPath, 'package.json');
-      if (!fs.existsSync(pkgPath)) {
-        return null;
-      }
-      const content = await fs.promises.readFile(pkgPath, 'utf-8');
-      const pkg = JSON.parse(content);
-      const scripts = pkg.scripts || {};
-      const commands = {};
-      const preferScript = (targetKey, names, label) => {
-        for (const name of names) {
-          if (Object.prototype.hasOwnProperty.call(scripts, name)) {
-            commands[targetKey] = {label, command: ['npm', 'run', name]};
-            break;
-          }
-        }
-      };
-      preferScript('build', ['build', 'compile', 'dist'], 'Build');
-      preferScript('test', ['test', 'check', 'spec'], 'Test');
-      preferScript('run', ['start', 'dev', 'serve', 'run'], 'Start');
-
-      const metadata = {
-        dependencies: gatherNodeDependencies(pkg),
-        scripts,
-        packageJson: pkg
-      };
-
-      return {
-        id: `${projectPath}::node`,
-        path: projectPath,
-        name: pkg.name || path.basename(projectPath),
-        type: 'Node.js',
-        icon: '🟢',
-        priority: this.priority,
-        commands,
-        metadata,
-        manifest: path.basename(manifest),
-        description: pkg.description || '',
-        extra: {
-          scripts: Object.keys(scripts)
-        }
-      };
-    }
-  },
-  {
-    type: 'python',
-    label: 'Python',
-    icon: '🐍',
-    priority: 80,
-    files: ['pyproject.toml', 'requirements.txt', 'setup.py'],
-    async build(projectPath, manifest) {
-      const commands = {};
-      if (fs.existsSync(path.join(projectPath, 'pyproject.toml'))) {
-        commands.test = {label: 'Pytest', command: ['pytest']};
-      } else {
-        commands.test = {label: 'Unittest', command: ['python', '-m', 'unittest', 'discover']};
-      }
-
-      const entry = await findPythonEntry(projectPath);
-      if (entry) {
-        commands.run = {label: 'Run', command: ['python', entry]};
-      }
-
-      const metadata = {
-        dependencies: gatherPythonDependencies(projectPath)
-      };
-
-      return {
-        id: `${projectPath}::python`,
-        path: projectPath,
-        name: path.basename(projectPath),
-        type: 'Python',
-        icon: '🐍',
-        priority: this.priority,
-        commands,
-        metadata,
-        manifest: path.basename(manifest),
-        description: '',
-        extra: {
-          entry
-        }
-      };
-    }
-  },
-  {
-    type: 'rust',
-    label: 'Rust',
-    icon: '🦀',
-    priority: 85,
-    files: ['Cargo.toml'],
-    async build(projectPath, manifest) {
-      return {
-        id: `${projectPath}::rust`,
-        path: projectPath,
-        name: path.basename(projectPath),
-        type: 'Rust',
-        icon: '🦀',
-        priority: this.priority,
-        commands: {
-          build: {label: 'Cargo build', command: ['cargo', 'build']},
-          test: {label: 'Cargo test', command: ['cargo', 'test']},
-          run: {label: 'Cargo run', command: ['cargo', 'run']}
-        },
-        metadata: {},
-        manifest: path.basename(manifest),
-        description: '',
-        extra: {}
-      };
-    }
-  },
-  {
-    type: 'go',
-    label: 'Go',
-    icon: '🐹',
-    priority: 80,
-    files: ['go.mod'],
-    async build(projectPath, manifest) {
-      return {
-        id: `${projectPath}::go`,
-        path: projectPath,
-        name: path.basename(projectPath),
-        type: 'Go',
-        icon: '🐹',
-        priority: this.priority,
-        commands: {
-          build: {label: 'Go build', command: ['go', 'build', './...']},
-          test: {label: 'Go test', command: ['go', 'test', './...']},
-          run: {label: 'Go run', command: ['go', 'run', '.']}
-        },
-        metadata: {},
-        manifest: path.basename(manifest),
-        description: '',
-        extra: {}
-      };
-    }
-  },
-  {
-    type: 'java',
-    label: 'Java',
-    icon: '☕️',
-    priority: 75,
-    files: ['pom.xml', 'build.gradle', 'build.gradle.kts'],
-    async build(projectPath, manifest) {
-      const hasMvnw = fs.existsSync(path.join(projectPath, 'mvnw'));
-      const hasGradlew = fs.existsSync(path.join(projectPath, 'gradlew'));
-      const commands = {};
-      if (hasGradlew) {
-        commands.build = {label: 'Gradle build', command: ['./gradlew', 'build']};
-        commands.test = {label: 'Gradle test', command: ['./gradlew', 'test']};
-      } else if (hasMvnw) {
-        commands.build = {label: 'Maven package', command: ['./mvnw', 'package']};
-        commands.test = {label: 'Maven test', command: ['./mvnw', 'test']};
-      } else {
-        commands.build = {label: 'Maven package', command: ['mvn', 'package']};
-        commands.test = {label: 'Maven test', command: ['mvn', 'test']};
-      }
-
-      return {
-        id: `${projectPath}::java`,
-        path: projectPath,
-        name: path.basename(projectPath),
-        type: 'Java',
-        icon: '☕️',
-        priority: this.priority,
-        commands,
-        metadata: {},
-        manifest: path.basename(manifest),
-        description: '',
-        extra: {}
-      };
-    }
-  },
-  {
-    type: 'scala',
-    label: 'Scala',
-    icon: '🔵',
-    priority: 70,
-    files: ['build.sbt'],
-    async build(projectPath, manifest) {
-      return {
-        id: `${projectPath}::scala`,
-        path: projectPath,
-        name: path.basename(projectPath),
-        type: 'Scala',
-        icon: '🔵',
-        priority: this.priority,
-        commands: {
-          build: {label: 'sbt compile', command: ['sbt', 'compile']},
-          test: {label: 'sbt test', command: ['sbt', 'test']},
-          run: {label: 'sbt run', command: ['sbt', 'run']}
-        },
-        metadata: {},
-        manifest: path.basename(manifest),
-        description: '',
-        extra: {}
-      };
-    }
-  }
-];
-
-async function findPythonEntry(projectPath) {
-  const candidates = ['main.py', 'app.py', 'src/main.py', 'src/app.py'];
-  for (const candidate of candidates) {
-    const candidatePath = path.join(projectPath, candidate);
-    if (fs.existsSync(candidatePath)) {
-      return candidate;
-    }
-  }
-  return null;
-}
-
-async function discoverProjects(root) {
-  const projectMap = new Map();
-  for (const schema of SCHEMAS) {
-    const patterns = schema.files.map((file) => `**/${file}`);
-    const matches = await fastGlob(patterns, {
-      cwd: root,
-      ignore: IGNORE_PATTERNS,
-      onlyFiles: true,
-      deep: 5
-    });
-
-    for (const match of matches) {
-      const projectDir = path.resolve(root, path.dirname(match));
-      const existing = projectMap.get(projectDir);
-      if (existing && existing.priority >= schema.priority) {
-        continue;
-      }
-      const entry = await schema.build(projectDir, match);
-      if (!entry) {
-        continue;
-      }
-      const withFrameworks = applyFrameworkPlugins(entry);
-      projectMap.set(projectDir, withFrameworks);
-    }
-  }
-  return Array.from(projectMap.values()).sort((a, b) => b.priority - a.priority);
-}
-
-const SCHEMA_GUIDE = SCHEMAS.map((schema) => ({
-  type: schema.type,
-  label: schema.label || schema.type,
-  icon: schema.icon || '⚙',
-  files: schema.files,
-  hint: schema.label || schema.type
-}));
-
-const ACTION_MAP = {
-  b: 'build',
-  t: 'test',
-  r: 'run'
-};
-const ART_CHARS = ['▁', '▃', '▄', '▅', '▇'];
-const ART_COLORS = ['magenta', 'blue', 'cyan', 'yellow', 'red'];
-const OUTPUT_WINDOW_SIZE = 8;
-const OUTPUT_WINDOW_HEIGHT = OUTPUT_WINDOW_SIZE + 2;
-const PROJECTS_MIN_WIDTH = 32;
-const DETAILS_MIN_WIDTH = 44;
-const HELP_CARD_MIN_WIDTH = 28;
-const RECENT_RUN_LIMIT = 5;
-
 function useScanner(rootPath) {
   const [state, setState] = useState({projects: [], loading: true, error: null});
 
@@ -996,11 +263,14 @@ function Compass({rootPath}) {
     }
 
     const normalizedInput = input?.toLowerCase();
-    if (normalizedInput === 'h') {
+    const ctrlCombo = (char) => key.ctrl && normalizedInput === char;
+    const shiftCombo = (char) => key.shift && normalizedInput === char;
+    const toggleShortcut = (char) => ctrlCombo(char) || shiftCombo(char);
+    if (toggleShortcut('h')) {
       setShowHelpCards((prev) => !prev);
       return;
     }
-    if (normalizedInput === 's') {
+    if (toggleShortcut('s')) {
       setShowStructureGuide((prev) => !prev);
       return;
     }
@@ -1048,7 +318,7 @@ function Compass({rootPath}) {
       setShowHelp((prev) => !prev);
       return;
     }
-    if (normalizedInput === 'l' && lastCommandRef.current) {
+    if (ctrlCombo('l') && lastCommandRef.current) {
       runProjectCommand(lastCommandRef.current.commandMeta, lastCommandRef.current.project);
       return;
     }
@@ -1068,7 +338,7 @@ function Compass({rootPath}) {
       setViewMode((prev) => (prev === 'detail' ? 'list' : 'detail'));
       return;
     }
-    if (normalizedInput === 'q') {
+    if (ctrlCombo('q')) {
       exit();
       return;
     }
@@ -1149,6 +419,11 @@ const projectRows = [];
     if (!detailedIndexed.length) {
       detailContent.push(create(Text, {dimColor: true}, 'No built-in commands yet. Add a custom command with C.'));
     }
+    const setupHints = selectedProject.extra?.setupHints || [];
+    if (setupHints.length) {
+      detailContent.push(create(Text, {dimColor: true, marginTop: 1}, 'Setup hints:'));
+      setupHints.forEach((hint) => detailContent.push(create(Text, {dimColor: true}, `  • ${hint}`)));
+    }
     detailContent.push(create(Text, {dimColor: true}, 'Press C → label|cmd to save custom actions, Enter to close detail view.'));
   } else {
     detailContent.push(create(Text, {dimColor: true}, 'Press Enter on a project to reveal details (icons, commands, frameworks, custom actions).'));
@@ -1250,19 +525,19 @@ const projectRows = [];
       color: 'magenta',
       body: [
         '↑ / ↓ move the project focus',
-        'Enter toggles detail view',
-        'Shift + ↑ / ↓ scrolls the log buffer',
-        'H toggles cards, ? opens the overlay'
+        'Enter opens or closes details',
+        'Shift + ↑ / ↓ scrolls only the log buffer',
+        'Ctrl+H toggles cards, ? opens the overlay'
       ]
     },
     {
       label: 'Command flow',
       color: 'cyan',
       body: [
-        'B / T / R run build / test / run',
-        '1-9 execute the numbered detail commands',
-        'L reruns the last command',
-        'Ctrl+C aborts, typing feeds stdin (buffer mirrors text)'
+        'B / T / R trigger build/test/run',
+        '1-9 execute detail commands in order',
+        'Ctrl+L reruns the last command you launched',
+        'Ctrl+C aborts, typing feeds stdin (buffer mirrors it)'
       ]
     },
     {
@@ -1270,12 +545,11 @@ const projectRows = [];
       color: 'yellow',
       body: [
         recentRuns.length ? `${recentRuns.length} runs recorded` : 'No runs yet · start with B/T/R',
-        'Press S to show the structure guide',
+        'Ctrl+S shows the structure guide when unsure',
         'Save custom commands with C → label|cmd'
       ]
     }
   ];
-
   const helpSection = showHelpCards
     ? create(
         Box,
@@ -1333,17 +607,17 @@ const projectRows = [];
         },
         create(Text, {color: 'cyan', bold: true}, 'Help overlay · press ? to hide'),
         create(Text, null, 'Shift+arrows scroll the output buffer.'),
-        create(Text, null, 'Run commands and type to feed stdin (Enter submits, Ctrl+C aborts); the buffer shows what you type.'),
-        create(Text, null, 'H hides/shows the navigation cards, S shows structure tips, and L reruns the previous command.'),
+        create(Text, null, 'Run commands and type to feed stdin (buffer mirrors your keystrokes, Enter submits, Ctrl+C aborts).'),
+        create(Text, null, 'Ctrl+H toggles the navigation cards, Ctrl+S shows structure tips, Ctrl+L reruns the previous command, Ctrl+Q quits.'),
         create(Text, null, 'Projects + Details stay side-by-side while Output and the log buffer stay fixed in their own band.'),
-        create(Text, null, 'Structure guide lists the manifests that trigger each language detection (press S to toggle).')
+        create(Text, null, 'Structure guide lists the manifests that trigger each language detection (press Ctrl+S to toggle).')
       )
     : null;
 
-  const toggleHint = showHelpCards ? 'H hides the help cards' : 'H shows the help cards';
+  const toggleHint = showHelpCards ? 'Ctrl+H hides the help cards' : 'Ctrl+H shows the help cards';
   const headerHint = viewMode === 'detail'
-    ? `Detail mode · 1-${Math.max(detailedIndexed.length, 1)} to execute, C: add custom commands, Enter: back to list, q: quit · ${toggleHint}, S shows structure guide`
-    : `Quick run · B/T/R to build/test/run, Enter: view details, q: quit · ${toggleHint}, S shows structure guide`;
+    ? `Detail mode · 1-${Math.max(detailedIndexed.length, 1)} to execute, C: add custom commands, Enter: back to list, Ctrl+Q: quit · ${toggleHint}, Ctrl+S shows structure guide`
+    : `Quick run · B/T/R to build/test/run, Enter: view details, Ctrl+Q: quit · ${toggleHint}, Ctrl+S shows structure guide`;
 
   return create(
     Box,