project-compass 2.0.1 → 2.1.0

package/README.md

@@ -1,18 +1,15 @@
-# Project Compass
+# Project Compass (v2.1.0)
 
-Project Compass is a futuristic CLI navigator built with [Ink](https://github.com/vadimdemedes/ink) that scans your current folder tree for familiar code projects and gives you one keystroke access to build, test, or run them.
+Project Compass is a futuristic CLI navigator built with [Ink](https://github.com/vadimdemedes/ink) that scans your current folder tree for familiar code projects and gives you one-keystroke access to build, test, or run them.
 
 ## Highlights
 
-- 🔍 Scans directories for Node.js, Python, Rust, Go, Java, and Scala projects by looking at their manifest files.
-- 🎨 Combines the glyph-based art board with a Projects/Details row that keeps everything inside the viewport, while live stdout/stderr logs stay in their own band below.
-- 🚀 Press **Enter** on any project to open the detail view, where you can inspect the type, manifest, frameworks, commands, and save custom actions.
-- 💡 A dedicated output row with an interactive stdin buffer, plus help tiles that stay in their own band; Shift+↑/↓ scrolls the log window, typing feeds stdin (buffer shows what you type, Enter submits, Ctrl+C aborts), Ctrl+L reruns the last command, Ctrl+H shows/hides the help cards, Ctrl+S opens the structure guide, and `?` pops an overlay with quick tips.
-- 🎯 Built-in shortcuts (B/T/R) run the canonical build/test/run workflow, while numeric hotkeys (1, 2, 3...) execute whichever command is listed in the detail view.
-- 🧠 Modular detection now scans for Node, Python, Rust, Go, Java, Scala, PHP, Ruby, .NET, shell/Makefile projects plus custom workspaces, and surface setup hints (npm install, pip install, cargo fetch, etc.).
-- 🧠 Add bespoke commands via **C** in detail view and store them globally (`~/.project-compass/config.json`) so every workspace remembers your favorite invocations.
-- 🔌 Extend detection via plugins (JSON specs under `~/.project-compass/plugins.json`) to teach Project Compass about extra frameworks or command sets.
-- 📦 Install globally and invoke `project-compass` from any folder to activate the UI instantly.
+- 🔍 Scans directories for Node.js, Python, Rust, Go, Java, and Scala projects.
+- 🎨 Futuristic layout with glyph-based art board and split Projects/Details rows.
+- 🚀 **New Keyboard-Centric UX**: Shortcuts now use **Shift** instead of Ctrl to avoid terminal interference.
+- 💡 **Refined Output**: Improved stdin buffer with proper spacing and reliable scrolling (Shift+↑/↓).
+- 🧠 **Smart Detection**: Support for 12+ frameworks with specialized build/run commands and setup hints.
+- 🔌 **Extensible**: Add custom commands with **C** and frameworks via `plugins.json`.
 
 ## Installation
 
@@ -26,83 +23,30 @@ npm install -g project-compass
 project-compass [--dir /path/to/workspace]
 ```
 
-### Keyboard guide
+### Keyboard Guide
 
 | Key | Action |
 | --- | --- |
-| ↑ / ↓ | Move the project focus, Enter toggles the detail view |
-| B / T / R | Run the workspace build/test/run shortcuts |
-| 1‑9 | Execute the numbered commands listed in detail view |
-| C | Add a custom command (`label|cmd`) that saves to `~/.project-compass/config.json` |
-| Shift ↑ / ↓ | Scroll the output buffer |
-| Ctrl+L | Rerun the most recent command |
-| ? | Toggle the help overlay with navigation tips |
-| Ctrl+H | Show/hide the navigation/help cards beneath the logs |
-| Ctrl+S | Toggle the structure guide listing the manifests per language |
-| Ctrl+Q | Quit the app |
-| Typing while running | Sends stdin to the running command (buffer shows the text, Enter submits, Ctrl+C aborts) |
-| Ctrl+C | Interrupt a running command (works while streaming output) |
+| ↑ / ↓ | Move focus, **Enter**: toggle details |
+| B / T / R | Build / Test / Run |
+| 1‑9 | Execute numbered detail commands |
+| C | Add a custom command (`label|cmd`) |
+| **Shift ↑ / ↓** | Scroll output buffer |
+| **Shift+L** | Rerun last command |
+| **Shift+H** | Toggle help cards |
+| **Shift+S** | Toggle structure guide |
+| **Shift+Q** | Quit app |
+| ? | Toggle help overlay |
+| Ctrl+C | Interrupt running command |
 
-## Framework & plugin support
+## Layout & UX
 
-Project Compass detects a wide range of modern stacks—**Next.js**, **React**, **Vue**, **NestJS**, **Angular**, **SvelteKit**, **Nuxt**, **Astro**, **Django**, **Flask**, **FastAPI**, and **Spring Boot**—and shows their badges in the detail view. When a framework is recognized, it injects framework-specific build/run/test commands (e.g., Next dev/build, Django runserver/test, Spring Boot run/test).
+Project Compass features a split layout where Projects and Details stay paired while Output takes a full-width band. The stdin buffer (at the bottom) now has a clear distinction between the label and your input for better readability. The help cards (Shift+H) have been refactored for a cleaner, more readable look.
 
-You can teach it new frameworks by adding a `plugins.json` file in your config directory (`~/.project-compass/plugins.json`). Each entry can declare the languages, files, dependencies, and commands that identify the framework. A sample plugin entry looks like this:
+## Frameworks
 
-```json
-{
-  "plugins": [
-    {
-      "name": "Remix",
-      "languages": ["Node.js"],
-      "files": ["remix.config.js"],
-      "dependencies": ["@remix-run/node"],
-      "commands": {
-        "run": "npm run dev",
-        "build": "npm run build"
-      }
-    }
-  ]
-}
-```
-
-Each command value can be a string or an array of tokens. When a plugin matches a project, its commands appear in the detail view with a `framework` badge, and the shortcut keys (B/T/R or numeric) can execute them.
-
-
-## Art board & detail view
-
-Project Compass now opens with a rounded art board that shuffles your glyph row (▁▃▄▅▇ with neon accents) and three branded tiles showing workspace pulse, the selected project focus, and the rhythm of commands. The detail view sits beside the project list as a gallery; border colors, badges, and the ambient header hint keep it feeling like a living installation rather than a vanilla CLI.
-
-## Layout, output & help
-
-Projects and details now occupy the same row, while the output panel takes its own full-width band beneath so long logs no longer stretch the rest of the UI. The output pane scrolls independently (Shift+↑/↓), feeds keystrokes into stdin while a command runs (type like normal, Enter submits, Ctrl+C aborts), and the buffer below shows exactly what you are typing. A trio of help tiles highlights navigation cues, command flow, and recent runs; they stay hidden by default—press Ctrl+H to reveal the cards, Ctrl+S to show the structure guide that lists the manifest files for each language detection, `?` to open the overlay with extra tips, Ctrl+L to rerun the previous command, and Ctrl+Q to quit.
-
-## Structure guide
-
-Press `S` to reveal the structure guide that lists which manifest files trigger each language detection (Node.js looks for `package.json`, Python looks for `pyproject.toml` or `requirements.txt`, Rust needs `Cargo.toml`, etc.). Use `H` to hide the help cards if you need every pixel for your output, then bring them back when you want a refresher.
-
-## Detection & setup hints
-
-Project Compass now has a modular detection engine (`src/projectDetection.js`) that looks at manifests, frameworks, and optional plugins to identify what kind of project you are standing in. Every schema fills `extra.setupHints` (npm install, pip install, go mod tidy, etc.) and those hints show up under the detail view whenever a project needs bootstrapping.
-
-Try the sample Python project at `/mnt/ramdisk/daily_builds/test_python_proj` (includes `pyproject.toml`, `requirements.txt`, and `app.py`) so you can run it via Project Compass and confirm stdin/input behavior.
-
-
-
-## Developer notes
-
-- `npm start` launches the Ink UI in the current directory.
-- `npm test` runs `node src/cli.js --mode test` to verify the scanner output.
-- Extend support for more languages by editing `SCHEMAS` or add plugin definitions under `~/.project-compass/plugins.json`.
-- Config lives at `~/.project-compass/config.json`. Drop custom commands there if you want to preseed them or share with teammates.
+Detects **Next.js**, **React**, **Vue**, **NestJS**, **FastAPI**, **Django**, and more. Recognizes frameworks and injects specialized commands automatically.
 
 ## License
 
 MIT © 2026 Satyaa & Clawdy
-
-## Release & packaging
-
-- Bump `package.json`/`package-lock.json` versions (e.g., `npm version 1.0.1 --no-git-tag-version`).
-- Run `npm run lint` and `npm run test` to validate the workspace before publishing.
-- Create the release artifact with `npm pack` (produces `project-compass-<version>.tgz` for uploading to GitHub Releases or npm).
-- Tag the repo `git tag v<version>` and push both commits and tags to publish the release.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-compass",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "Ink-based project explorer that detects local repos and lets you build/test/run them without memorizing commands.",
   "main": "src/cli.js",
   "type": "module",

package/src/cli.js

@@ -265,7 +265,7 @@ function Compass({rootPath}) {
     const normalizedInput = input?.toLowerCase();
     const ctrlCombo = (char) => key.ctrl && normalizedInput === char;
     const shiftCombo = (char) => key.shift && normalizedInput === char;
-    const toggleShortcut = (char) => ctrlCombo(char) || shiftCombo(char);
+    const toggleShortcut = (char) => shiftCombo(char);
     if (toggleShortcut('h')) {
       setShowHelpCards((prev) => !prev);
       return;
@@ -306,11 +306,11 @@ function Compass({rootPath}) {
     }
 
     if (key.shift && key.upArrow) {
-      scrollLogs(1);
+      scrollLogs(-1);
       return;
     }
     if (key.shift && key.downArrow) {
-      scrollLogs(-1);
+      scrollLogs(1);
       return;
     }
 
@@ -318,7 +318,7 @@ function Compass({rootPath}) {
       setShowHelp((prev) => !prev);
       return;
     }
-    if (ctrlCombo('l') && lastCommandRef.current) {
+    if (shiftCombo('l') && lastCommandRef.current) {
       runProjectCommand(lastCommandRef.current.commandMeta, lastCommandRef.current.project);
       return;
     }
@@ -338,7 +338,7 @@ function Compass({rootPath}) {
       setViewMode((prev) => (prev === 'detail' ? 'list' : 'detail'));
       return;
     }
-    if (ctrlCombo('q')) {
+    if (shiftCombo('q')) {
       exit();
       return;
     }
@@ -525,19 +525,19 @@ const projectRows = [];
       color: 'magenta',
       body: [
         '↑ / ↓ move the project focus',
-        'Enter opens or closes details',
-        'Shift + ↑ / ↓ scrolls only the log buffer',
-        'Ctrl+H toggles cards, ? opens the overlay'
+        'Enter toggles details view',
+        'Shift+↑ / ↓ scroll output buffer',
+        'Shift+H toggles help cards'
       ]
     },
     {
       label: 'Command flow',
       color: 'cyan',
       body: [
-        '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)'
+        'B / T / R run build/test/run',
+        '1-9 execute detail commands',
+        'Shift+L reruns last command',
+        'Ctrl+C aborts; type feeds stdin'
       ]
     },
     {
@@ -545,8 +545,9 @@ const projectRows = [];
       color: 'yellow',
       body: [
         recentRuns.length ? `${recentRuns.length} runs recorded` : 'No runs yet · start with B/T/R',
-        'Ctrl+S shows the structure guide when unsure',
-        'Save custom commands with C → label|cmd'
+        'Shift+S toggles structure guide',
+        'C save custom action',
+        'Shift+Q quit application'
       ]
     }
   ];
@@ -566,16 +567,17 @@ const projectRows = [];
               marginBottom: 1,
               borderStyle: 'round',
               borderColor: card.color,
-              padding: 1
+              padding: 1,
+              flexDirection: 'column'
             },
-            create(Text, {color: card.color, bold: true}, card.label),
+            create(Text, {color: card.color, bold: true, marginBottom: 1}, card.label),
             ...card.body.map((line, lineIndex) =>
               create(Text, {key: `${card.label}-${lineIndex}`, dimColor: card.color === 'yellow'}, line)
             )
           )
         )
       )
-    : create(Text, {dimColor: true, marginTop: 1}, 'Help cards hidden · press H to show navigation, command flow, and recent runs.');
+    : create(Text, {dimColor: true, marginTop: 1}, 'Help cards hidden · press Shift+H to show navigation, command flow, and recent runs.');
 
   const structureGuide = showStructureGuide
     ? create(
@@ -587,7 +589,7 @@ const projectRows = [];
           marginTop: 1,
           padding: 1
         },
-        create(Text, {color: 'cyan', bold: true}, 'Project structure guide · press S to hide'),
+        create(Text, {color: 'cyan', bold: true}, 'Project structure guide · press Shift+S to hide'),
         ...SCHEMA_GUIDE.map((entry) =>
           create(Text, {key: entry.type, dimColor: true}, `• ${entry.icon} ${entry.label}: ${entry.files.join(', ')}`)
         ),
@@ -606,18 +608,18 @@ const projectRows = [];
           padding: 1
         },
         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 (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 Ctrl+S to toggle).')
+        create(Text, null, 'Shift+↑/↓ scrolls the log buffer while commands stream; type to feed stdin (Enter submits, Ctrl+C aborts).'),
+        create(Text, null, 'B/T/R run build/test/run; 1-9 executes detail commands; Ctrl+L reruns the previous command.'),
+        create(Text, null, 'Ctrl+H toggles these help cards, Ctrl+S toggles the structure guide, ? toggles this overlay, Ctrl+Q quits.'),
+        create(Text, null, 'Projects + Details stay paired while Output keeps its own full-width band.'),
+        create(Text, null, 'Structure guide lists the manifests that trigger each language detection (Ctrl+S to toggle).')
       )
     : null;
 
-  const toggleHint = showHelpCards ? 'Ctrl+H hides the help cards' : 'Ctrl+H shows the help cards';
+  const toggleHint = showHelpCards ? 'Shift+H hides the help cards' : 'Shift+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, 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`;
+    ? `Detail mode · 1-${Math.max(detailedIndexed.length, 1)} to execute, C: add custom commands, Enter: back to list, Shift+Q: quit · ${toggleHint}, Shift+S toggles structure guide`
+    : `Quick run · B/T/R to build/test/run, Enter: view details, Shift+Q: quit · ${toggleHint}, Shift+S toggles structure guide`;
 
   return create(
     Box,
@@ -702,7 +704,7 @@ const projectRows = [];
         Box,
         {marginTop: 1, flexDirection: 'row', justifyContent: 'space-between'},
         create(Text, {dimColor: true}, running ? 'Type to feed stdin; Enter submits, Ctrl+C aborts.' : 'Run a command or press ? for extra help.'),
-        create(Text, {dimColor: true}, `${toggleHint}, S toggles the structure guide`)
+        create(Text, {dimColor: true}, `${toggleHint}, Shift+S toggles the structure guide`)
       ),
       create(
         Box,
@@ -711,9 +713,9 @@ const projectRows = [];
           flexDirection: 'row',
           borderStyle: 'round',
           borderColor: running ? 'green' : 'gray',
-          padding: 1
+          paddingX: 1
         },
-        create(Text, {bold: true, color: running ? 'green' : 'white'}, running ? 'Stdin buffer' : 'Input ready'),
+        create(Text, {bold: true, color: running ? 'green' : 'white'}, running ? ' Stdin buffer ' : ' Input ready '),
         create(Text, {dimColor: true, marginLeft: 1}, running ? (stdinBuffer || '(type to send)') : 'Start a command to feed stdin')
       )
     ),

package/src/projectDetection.js

@@ -5,6 +5,12 @@ import {ensureConfigDir, PLUGIN_FILE} from './configPaths.js';
 
 const IGNORE_PATTERNS = ['**/node_modules/**', '**/.git/**', '**/dist/**', '**/build/**', '**/target/**'];
 
+const PYTHON_ENTRY_FILES = ['main.py', 'app.py', 'src/main.py', 'src/app.py'];
+
+function findPythonEntry(projectPath) {
+  return PYTHON_ENTRY_FILES.find((file) => hasProjectFile(projectPath, file)) || null;
+}
+
 function hasProjectFile(projectPath, file) {
   return fs.existsSync(path.join(projectPath, file));
 }
@@ -316,10 +322,14 @@ const builtInFrameworks = [
     languages: ['Python'],
     priority: 105,
     match(project) {
-      return dependencyMatches(project, 'flask') || hasProjectFile(project.path, 'app.py');
+      const entry = findPythonEntry(project.path);
+      return Boolean(entry && dependencyMatches(project, 'flask'));
     },
     commands(project) {
-      const entry = hasProjectFile(project.path, 'app.py') ? 'app.py' : 'main.py';
+      const entry = findPythonEntry(project.path);
+      if (!entry) {
+        return {};
+      }
       return {
         run: {label: 'Flask app', command: ['python', entry], source: 'framework'},
         test: {label: 'Pytest', command: ['pytest'], source: 'framework'}
@@ -334,12 +344,17 @@ const builtInFrameworks = [
     languages: ['Python'],
     priority: 105,
     match(project) {
-      return dependencyMatches(project, 'fastapi');
+      const entry = findPythonEntry(project.path);
+      return Boolean(entry && dependencyMatches(project, 'fastapi'));
     },
     commands(project) {
-      const entry = hasProjectFile(project.path, 'main.py') ? 'main.py' : 'app.py';
+      const entry = findPythonEntry(project.path);
+      if (!entry) {
+        return {};
+      }
+      const moduleName = entry.split('.').slice(0, -1).join('.') || entry;
       return {
-        run: {label: 'Uvicorn reload', command: ['uvicorn', `${entry.split('.')[0]}:app`, '--reload'], source: 'framework'},
+        run: {label: 'Uvicorn reload', command: ['uvicorn', `${moduleName}:app`, '--reload'], source: 'framework'},
         test: {label: 'Pytest', command: ['pytest'], source: 'framework'}
       };
     }
@@ -458,7 +473,7 @@ class SchemaRegistry {
             commands.test = {label: 'Unittest', command: ['python', '-m', 'unittest', 'discover']};
           }
 
-          const entry = this.findPythonEntry(projectPath);
+          const entry = findPythonEntry(projectPath);
           if (entry) {
             commands.run = {label: 'Run', command: ['python', entry]};
           }
@@ -492,15 +507,6 @@ class SchemaRegistry {
             }
           };
         },
-        findPythonEntry(projectPath) {
-          const candidates = ['main.py', 'app.py', 'src/main.py', 'src/app.py'];
-          for (const candidate of candidates) {
-            if (hasProjectFile(projectPath, candidate)) {
-              return candidate;
-            }
-          }
-          return null;
-        }
       },
       {
         type: 'rust',