project-compass 2.0.2 → 2.2.0

package/README.md

@@ -1,18 +1,15 @@
-# Project Compass
+# Project Compass (v2.2.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 15+ frameworks (Vite, Prisma, Tailwind, etc.) with specialized build/run commands and setup hints.
+- 🔌 **Extensible**: Add custom commands with **Shift+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 |
+| **Shift+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 `Ctrl+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 `Ctrl+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**, **Vite**, **Prisma**, **Tailwind**, 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.2",
+  "version": "2.2.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;
@@ -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,11 +338,11 @@ function Compass({rootPath}) {
       setViewMode((prev) => (prev === 'detail' ? 'list' : 'detail'));
       return;
     }
-    if (ctrlCombo('q')) {
+    if (shiftCombo('q')) {
       exit();
       return;
     }
-    if (normalizedInput === 'c' && viewMode === 'detail' && selectedProject) {
+    if (shiftCombo('c') && viewMode === 'detail' && selectedProject) {
       setCustomMode(true);
       setCustomInput('');
       return;
@@ -412,19 +412,19 @@ const projectRows = [];
     detailContent.push(create(Text, {bold: true, marginTop: 1}, 'Commands'));
     detailedIndexed.forEach((command) => {
       detailContent.push(
-        create(Text, {key: `detail-${command.shortcut}-${command.label}`}, `${command.shortcut}. ${command.label} ${command.source === 'custom' ? kleur.magenta('(custom)') : command.source === 'framework' ? kleur.cyan('(framework)') : ''}`)
+        create(Text, {key: `detail-${command.shortcut}-${command.label}`}, `${command.shortcut}. ${command.label} ${command.source === 'custom' ? kleur.magenta('(custom)') : command.source === 'framework' ? kleur.cyan('(framework)') : command.source === 'plugin' ? kleur.green('(plugin)') : ''}`)
       );
       detailContent.push(create(Text, {dimColor: true}, `   ↳ ${command.command.join(' ')}`));
     });
     if (!detailedIndexed.length) {
-      detailContent.push(create(Text, {dimColor: true}, 'No built-in commands yet. Add a custom command with C.'));
+      detailContent.push(create(Text, {dimColor: true}, 'No built-in commands yet. Add a custom command with Shift+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.'));
+    detailContent.push(create(Text, {dimColor: true}, 'Press Shift+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).'));
   }
@@ -524,19 +524,20 @@ const projectRows = [];
       label: 'Navigation',
       color: 'magenta',
       body: [
-        '↑ / ↓ move the project focus, Enter toggles details',
-        'Shift+↑ / Shift+↓ scroll only the output buffer',
-        'Ctrl+H toggles cards, ? opens the overlay'
+        '↑ / ↓ move the project focus',
+        '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 shortcuts',
-        '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'
       ]
     },
     {
@@ -544,8 +545,9 @@ const projectRows = [];
       color: 'yellow',
       body: [
         recentRuns.length ? `${recentRuns.length} runs recorded` : 'No runs yet · start with B/T/R',
-        'Ctrl+S toggles the structure guide when unsure',
-        'C → label|cmd saves a custom action'
+        'Shift+S toggles structure guide',
+        'Shift+C save custom action',
+        'Shift+Q quit application'
       ]
     }
   ];
@@ -565,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 Ctrl+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(
@@ -586,7 +589,7 @@ const projectRows = [];
           marginTop: 1,
           padding: 1
         },
-        create(Text, {color: 'cyan', bold: true}, 'Project structure guide · press Ctrl+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(', ')}`)
         ),
@@ -613,10 +616,10 @@ const projectRows = [];
       )
     : 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 toggles structure guide`
-    : `Quick run · B/T/R to build/test/run, Enter: view details, Ctrl+Q: quit · ${toggleHint}, Ctrl+S toggles structure guide`;
+    ? `Detail mode · 1-${Math.max(detailedIndexed.length, 1)} to execute, Shift+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,
@@ -701,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}, Ctrl+S toggles the structure guide`)
+        create(Text, {dimColor: true}, `${toggleHint}, Shift+S toggles the structure guide`)
       ),
       create(
         Box,
@@ -710,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

@@ -323,7 +323,7 @@ const builtInFrameworks = [
     priority: 105,
     match(project) {
       const entry = findPythonEntry(project.path);
-      return Boolean(entry && dependencyMatches(project, 'flask'));
+      return Boolean(entry && (dependencyMatches(project, 'flask') || dependencyMatches(project, 'flask-restful') || dependencyMatches(project, 'flask-cors')));
     },
     commands(project) {
       const entry = findPythonEntry(project.path);
@@ -345,7 +345,7 @@ const builtInFrameworks = [
     priority: 105,
     match(project) {
       const entry = findPythonEntry(project.path);
-      return Boolean(entry && dependencyMatches(project, 'fastapi'));
+      return Boolean(entry && (dependencyMatches(project, 'fastapi') || dependencyMatches(project, 'pydantic') || dependencyMatches(project, 'uvicorn')));
     },
     commands(project) {
       const entry = findPythonEntry(project.path);
@@ -359,6 +359,59 @@ const builtInFrameworks = [
       };
     }
   },
+  {
+    id: 'vite',
+    name: 'Vite',
+    icon: '⚡',
+    description: 'Vite-powered frontend',
+    languages: ['Node.js'],
+    priority: 100,
+    match(project) {
+      return hasProjectFile(project.path, 'vite.config.js') || hasProjectFile(project.path, 'vite.config.ts') || 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', 'Vite dev', () => ['npx', 'vite']);
+      add('build', 'Vite build', () => ['npx', 'vite', 'build']);
+      add('preview', 'Vite preview', () => ['npx', 'vite', 'preview']);
+      return commands;
+    }
+  },
+  {
+    id: 'tailwind',
+    name: 'Tailwind CSS',
+    icon: '🎨',
+    description: 'Tailwind utility-first CSS',
+    languages: ['Node.js'],
+    priority: 50,
+    match(project) {
+      return hasProjectFile(project.path, 'tailwind.config.js') || hasProjectFile(project.path, 'tailwind.config.ts') || dependencyMatches(project, 'tailwindcss');
+    },
+    commands() { return {}; }
+  },
+  {
+    id: 'prisma',
+    name: 'Prisma',
+    icon: '◮',
+    description: 'Prisma ORM',
+    languages: ['Node.js'],
+    priority: 50,
+    match(project) {
+      return hasProjectFile(project.path, 'prisma/schema.prisma') || dependencyMatches(project, '@prisma/client');
+    },
+    commands() {
+      return {
+        generate: {label: 'Prisma generate', command: ['npx', 'prisma', 'generate'], source: 'framework'},
+        studio: {label: 'Prisma studio', command: ['npx', 'prisma', 'studio'], source: 'framework'}
+      };
+    }
+  },
   {
     id: 'spring',
     name: 'Spring Boot',