project-compass 1.0.1 → 1.0.2

package/README.md

@@ -5,11 +5,11 @@ Project Compass is a futuristic CLI navigator built with [Ink](https://github.co
 ## Highlights
 
 - 🔍 Scans directories for Node.js, Python, Rust, Go, Java, and Scala projects by looking at their manifest files.
-- ✨ Presents a modern Ink dashboard with an interactive project list, icons, and live stdout/stderr logs.
+- 🎨 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 + help tiles keep logs in one pane, support smooth refresh (Shift+↑/↓ or mouse wheel to scroll, typing feeds stdin, Ctrl+C aborts, L reruns the last command) and include a `?` overlay for quick navigation 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.
 - 🧠 Add bespoke commands via **C** in detail view and store them globally (`~/.project-compass/config.json`) so every workspace remembers your favorite invocations.
-- 🎨 The top art board layers glyphs, neon-like tiles, and highlighted metrics (Pulse, Focus, Rhythm) so the CLI feels like a curated gallery instead of a bland table.
 - 🔌 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.
 
@@ -34,6 +34,10 @@ project-compass [--dir /path/to/workspace]
 | B / T / R | Quick build / test / run actions (when available) |
 | 1‑9 | Execute the numbered command inside the detail view |
 | C | Add a custom command (`label|cmd`) that saves to `~/.project-compass/config.json` |
+| Shift ↑ / ↓ | Scroll the output buffer (Shift+arrows or mouse wheel) |
+| L | Rerun the last executed command |
+| ? | Toggle the help overlay with navigation tips |
+| Ctrl+C | Interrupt a running command (works while streaming output) |
 | Q | Quit |
 
 ## Framework & plugin support
@@ -66,6 +70,10 @@ Each command value can be a string or an array of tokens. When a plugin matches
 
 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+↑/↓ or mouse wheel), accepts keystrokes to feed stdin while a command runs, and honors Ctrl+C to abort. A trio of help tiles underneath highlights navigation cues, command flow, and recent runs, and pressing `?` opens an overlay with extra tips (for example, left-click cycles the project focus, L reruns the last command, and the help overlay reminds you about the new shortcuts).
+
 ## Developer notes
 
 - `npm start` launches the Ink UI in the current directory.
@@ -76,6 +84,7 @@ Project Compass now opens with a rounded art board that shuffles your glyph row
 ## 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`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-compass",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "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

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import React, {useCallback, useEffect, useMemo, useState} from 'react';
+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';
@@ -771,6 +771,8 @@ const ACTION_MAP = {
 };
 const ART_CHARS = ['▁', '▃', '▄', '▅', '▇'];
 const ART_COLORS = ['magenta', 'blue', 'cyan', 'yellow', 'red'];
+const OUTPUT_WINDOW_SIZE = 10;
+const RECENT_RUN_LIMIT = 5;
 
 function useScanner(rootPath) {
   const [state, setState] = useState({projects: [], loading: true, error: null});
@@ -820,16 +822,25 @@ function Compass({rootPath}) {
   const [selectedIndex, setSelectedIndex] = useState(0);
   const [viewMode, setViewMode] = useState('list');
   const [logLines, setLogLines] = useState([]);
+  const [logOffset, setLogOffset] = useState(0);
   const [running, setRunning] = useState(false);
   const [lastAction, setLastAction] = useState(null);
   const [customMode, setCustomMode] = useState(false);
   const [customInput, setCustomInput] = useState('');
   const [config, setConfig] = useState(() => loadConfig());
-
+  const [showHelp, setShowHelp] = useState(false);
+  const [recentRuns, setRecentRuns] = useState([]);
   const selectedProject = projects[selectedIndex] || null;
+  const runningProcessRef = useRef(null);
+  const lastCommandRef = useRef(null);
 
   const addLog = useCallback((line) => {
-    setLogLines((prev) => [...prev.slice(-200), typeof line === 'string' ? line : JSON.stringify(line)]);
+    setLogLines((prev) => {
+      const normalized = typeof line === 'string' ? line : JSON.stringify(line);
+      const next = [...prev, normalized];
+      return next.length > 250 ? next.slice(next.length - 250) : next;
+    });
+    setLogOffset(0);
   }, []);
 
   const detailCommands = useMemo(() => buildDetailCommands(selectedProject, config), [selectedProject, config]);
@@ -843,8 +854,9 @@ function Compass({rootPath}) {
     return map;
   }, [detailedIndexed]);
 
-  const runProjectCommand = useCallback(async (commandMeta) => {
-    if (!selectedProject) {
+  const runProjectCommand = useCallback(async (commandMeta, targetProject = selectedProject) => {
+    const project = targetProject || selectedProject;
+    if (!project) {
       return;
     }
     if (!commandMeta || !Array.isArray(commandMeta.command) || commandMeta.command.length === 0) {
@@ -856,16 +868,24 @@ function Compass({rootPath}) {
       return;
     }
 
+    const commandLabel = commandMeta.label || commandMeta.command.join(' ');
+    lastCommandRef.current = {project, commandMeta};
     setRunning(true);
-    setLastAction(`${selectedProject.name} · ${commandMeta.label}`);
+    setLastAction(`${project.name} · ${commandLabel}`);
     const fullCmd = commandMeta.command;
     addLog(kleur.cyan(`> ${fullCmd.join(' ')}`));
+    setRecentRuns((prev) => {
+      const entry = {project: project.name, command: commandLabel, time: new Date().toLocaleTimeString()};
+      return [entry, ...prev].slice(0, RECENT_RUN_LIMIT);
+    });
 
     try {
       const subprocess = execa(fullCmd[0], fullCmd.slice(1), {
-        cwd: selectedProject.path,
-        env: process.env
+        cwd: project.path,
+        env: process.env,
+        stdin: 'pipe'
       });
+      runningProcessRef.current = subprocess;
 
       subprocess.stdout?.on('data', (chunk) => {
         addLog(chunk.toString().trimEnd());
@@ -875,13 +895,14 @@ function Compass({rootPath}) {
       });
 
       await subprocess;
-      addLog(kleur.green(`✓ ${commandMeta.label} finished`));
+      addLog(kleur.green(`✓ ${commandLabel} finished`));
     } catch (error) {
-      addLog(kleur.red(`✗ ${commandMeta.label} failed: ${error.shortMessage || error.message}`));
+      addLog(kleur.red(`✗ ${commandLabel} failed: ${error.shortMessage || error.message}`));
     } finally {
       setRunning(false);
+      runningProcessRef.current = null;
     }
-  }, [selectedProject, addLog, running]);
+  }, [addLog, running, selectedProject]);
 
   const handleAddCustomCommand = useCallback((label, commandTokens) => {
     if (!selectedProject) {
@@ -951,11 +972,57 @@ function Compass({rootPath}) {
       return;
     }
 
-    if (key.upArrow && projects.length > 0) {
+    if (key.mouse) {
+      if (key.mouse === 'left' && projects.length > 0) {
+        setSelectedIndex((prev) => (prev + 1) % projects.length);
+      } else if (key.mouse === 'scrollUp') {
+        const maxScroll = Math.max(0, logLines.length - OUTPUT_WINDOW_SIZE);
+        setLogOffset((prev) => Math.min(maxScroll, prev + 1));
+      } else if (key.mouse === 'scrollDown') {
+        setLogOffset((prev) => Math.max(0, prev - 1));
+      }
+      return;
+    }
+
+    if (running && runningProcessRef.current) {
+      if (key.ctrl && input === 'c') {
+        runningProcessRef.current.kill('SIGINT');
+        return;
+      }
+      if (key.return) {
+        runningProcessRef.current.stdin?.write('\n');
+        return;
+      }
+      if (input) {
+        runningProcessRef.current.stdin?.write(input);
+      }
+      return;
+    }
+
+    if (key.shift && key.upArrow) {
+      const maxScroll = Math.max(0, logLines.length - OUTPUT_WINDOW_SIZE);
+      setLogOffset((prev) => Math.min(maxScroll, prev + 1));
+      return;
+    }
+    if (key.shift && key.downArrow) {
+      setLogOffset((prev) => Math.max(0, prev - 1));
+      return;
+    }
+
+    if (input === '?') {
+      setShowHelp((prev) => !prev);
+      return;
+    }
+    if (input === 'l' && lastCommandRef.current) {
+      runProjectCommand(lastCommandRef.current.commandMeta, lastCommandRef.current.project);
+      return;
+    }
+
+    if (key.upArrow && !key.shift && projects.length > 0) {
       setSelectedIndex((prev) => (prev - 1 + projects.length) % projects.length);
       return;
     }
-    if (key.downArrow && projects.length > 0) {
+    if (key.downArrow && !key.shift && projects.length > 0) {
       setSelectedIndex((prev) => (prev + 1) % projects.length);
       return;
     }
@@ -977,17 +1044,17 @@ function Compass({rootPath}) {
     }
     if (ACTION_MAP[input]) {
       const commandMeta = selectedProject?.commands?.[ACTION_MAP[input]];
-      runProjectCommand(commandMeta);
+      runProjectCommand(commandMeta, selectedProject);
       return;
     }
     if (viewMode === 'detail' && detailShortcutMap.has(input)) {
-      runProjectCommand(detailShortcutMap.get(input));
+      runProjectCommand(detailShortcutMap.get(input), selectedProject);
     }
   });
 
   const projectRows = [];
   if (loading) {
-    projectRows.push(create(Text, {dimColor: true}, 'Scanning for projects…'));
+    projectRows.push(create(Text, {dimColor: true}, 'Scanning projects…'));
   }
   if (error) {
     projectRows.push(create(Text, {color: 'red'}, `Unable to scan: ${error}`));
@@ -1002,21 +1069,17 @@ function Compass({rootPath}) {
       projectRows.push(
         create(
           Box,
-          {key: project.id, flexDirection: 'column', marginBottom: 1},
+          {key: project.id, flexDirection: 'column', marginBottom: 1, padding: 1},
           create(
-            Box,
-            {flexDirection: 'row'},
-            create(
-              Text,
-              {
-                color: isSelected ? 'cyan' : 'white',
-                bold: isSelected
-              },
-              `${project.icon} ${project.name}`
-            ),
-            create(Text, {color: 'gray'}, `  ${project.type} · ${path.relative(rootPath, project.path) || '.'}`)
+            Text,
+            {
+              color: isSelected ? 'cyan' : 'white',
+              bold: isSelected
+            },
+            `${project.icon} ${project.name}`
           ),
-          frameworkBadges && create(Text, {color: isSelected ? 'cyan' : 'gray'}, `   ${frameworkBadges}`)
+          create(Text, {dimColor: true}, `  ${project.type} · ${path.relative(rootPath, project.path) || '.'}`),
+          frameworkBadges && create(Text, {dimColor: true}, `   ${frameworkBadges}`)
         )
       );
     });
@@ -1025,7 +1088,7 @@ function Compass({rootPath}) {
   const detailContent = [];
   if (viewMode === 'detail' && selectedProject) {
     detailContent.push(
-      create(Text, {color: 'yellow', bold: true}, `${selectedProject.icon} ${selectedProject.name}`),
+      create(Text, {color: 'cyan', bold: true}, `${selectedProject.icon} ${selectedProject.name}`),
       create(Text, {dimColor: true}, `${selectedProject.type} · ${selectedProject.manifest || 'detected manifest'}`),
       create(Text, {dimColor: true}, `Location: ${path.relative(rootPath, selectedProject.path) || '.'}`)
     );
@@ -1044,7 +1107,7 @@ function Compass({rootPath}) {
     detailContent.push(create(Text, {bold: true, marginTop: 1}, 'Commands'));
     detailedIndexed.forEach((command) => {
       detailContent.push(
-        create(Text, {key: `${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)') : ''}`)
       );
       detailContent.push(create(Text, {dimColor: true}, `   ↳ ${command.command.join(' ')}`));
     });
@@ -1060,24 +1123,20 @@ function Compass({rootPath}) {
     detailContent.push(create(Text, {color: 'cyan'}, `Type label|cmd (Enter to save, Esc to cancel): ${customInput}`));
   }
 
-  const logNodes = logLines.length
-    ? logLines.map((line, index) => create(Text, {key: `${line}-${index}`}, line))
-    : [create(Text, {dimColor: true}, 'Logs will appear here once you run a command.')];
-
   const projectCountLabel = `${projects.length} project${projects.length === 1 ? '' : 's'}`;
   const artTileNodes = useMemo(() => {
     const selectedName = selectedProject?.name || 'Awaiting selection';
     const selectedType = selectedProject?.type || 'Unknown stack';
     const selectedLocation = selectedProject?.path ? path.relative(rootPath, selectedProject.path) || '.' : '—';
-    const motionNarrative = running ? 'Executing...' : lastAction ? `Last: ${lastAction}` : 'Idle in palette';
-    const rootName = path.basename(rootPath) || rootPath;
+    const statusNarrative = running ? 'Running commands' : lastAction ? `Last: ${lastAction}` : 'Idle gallery';
+    const workspaceName = path.basename(rootPath) || rootPath;
     const tileDefinition = [
       {
         label: 'Pulse',
         detail: projectCountLabel,
         accent: 'magenta',
         icon: '●',
-        subtext: `Workspace · ${rootName}`
+        subtext: `Workspace · ${workspaceName}`
       },
       {
         label: 'Focus',
@@ -1091,7 +1150,7 @@ function Compass({rootPath}) {
         detail: `${detailCommands.length} commands`,
         accent: 'yellow',
         icon: '■',
-        subtext: motionNarrative
+        subtext: statusNarrative
       }
     ];
     return tileDefinition.map((tile) =>
@@ -1104,14 +1163,14 @@ function Compass({rootPath}) {
           marginRight: 1,
           borderStyle: 'single',
           borderColor: tile.accent,
-          minWidth: 22
+          minWidth: 24
         },
         create(Text, {color: tile.accent, bold: true}, `${tile.icon} ${tile.label}`),
         create(Text, {bold: true}, tile.detail),
         create(Text, {dimColor: true}, tile.subtext)
       )
     );
-  }, [projectCountLabel, rootPath, selectedProject?.name, selectedProject?.type, selectedProject?.path, detailCommands.length, running, lastAction]);
+  }, [projectCountLabel, rootPath, selectedProject, detailCommands.length, running, lastAction]);
 
   const artBoard = create(
     Box,
@@ -1119,14 +1178,20 @@ function Compass({rootPath}) {
       flexDirection: 'column',
       marginTop: 1,
       borderStyle: 'round',
-      borderColor: 'white',
+      borderColor: 'gray',
       padding: 1
     },
     create(
       Box,
       {flexDirection: 'row', justifyContent: 'space-between'},
+      create(Text, {color: 'magenta', bold: true}, 'Art-coded build atlas'),
+      create(Text, {dimColor: true}, 'press ? for overlay help')
+    ),
+    create(
+      Box,
+      {flexDirection: 'row', marginTop: 1},
       ...ART_CHARS.map((char, index) =>
-        create(Text, {key: `art-char-${index}`, color: ART_COLORS[index % ART_COLORS.length]}, char.repeat(2))
+        create(Text, {key: `art-${index}`, color: ART_COLORS[index % ART_COLORS.length]}, char.repeat(2))
       )
     ),
     create(
@@ -1134,9 +1199,86 @@ function Compass({rootPath}) {
       {flexDirection: 'row', marginTop: 1},
       ...artTileNodes
     ),
-    create(Text, {dimColor: true, marginTop: 1}, kleur.italic('Terminal art mosaic · vibe meets productivity'))
+    create(Text, {dimColor: true, marginTop: 1}, kleur.italic('The art board now follows your layout and stays inside the window.'))
+  );
+
+  const logWindowStart = Math.max(0, logLines.length - OUTPUT_WINDOW_SIZE - logOffset);
+  const logWindowEnd = Math.max(0, logLines.length - logOffset);
+  const visibleLogs = logLines.slice(logWindowStart, logWindowEnd);
+  const logNodes = visibleLogs.length
+    ? visibleLogs.map((line, index) => create(Text, {key: `${logWindowStart + index}-${line}`}, line))
+    : [create(Text, {dimColor: true}, 'Logs will appear here once you run a command.')];
+
+  const helpCards = [
+    {
+      label: 'Navigation',
+      color: 'magenta',
+      body: [
+        '↑/↓ select projects, Enter toggles detail view',
+        'Shift+↑/↓ or mouse wheel scrolls logs',
+        '? toggles this overlay, left click cycles the list'
+      ]
+    },
+    {
+      label: 'Command flow',
+      color: 'cyan',
+      body: [
+        'B/T/R run build/test/run for the focused project',
+        '1-9 execute the numbered detail commands',
+        'L reruns the last command, Ctrl+C aborts it',
+        'Type while a command is running to feed stdin'
+      ]
+    },
+    {
+      label: 'Recent runs',
+      color: 'yellow',
+      body: recentRuns.length
+        ? recentRuns.map((run) => `${run.time} · ${run.project}: ${run.command}`)
+        : ['No runs yet. Start one with B/T/R.']
+    }
+  ];
+
+  const helpSection = create(
+    Box,
+    {marginTop: 1, flexDirection: 'row', justifyContent: 'space-between'},
+    ...helpCards.map((card, index) =>
+      create(
+        Box,
+        {
+          key: card.label,
+          flexGrow: 1,
+          flexBasis: 0,
+          marginRight: index < helpCards.length - 1 ? 1 : 0,
+          borderStyle: 'round',
+          borderColor: card.color,
+          padding: 1
+        },
+        create(Text, {color: card.color, bold: true}, card.label),
+        ...card.body.map((line, lineIndex) =>
+          create(Text, {key: `${card.label}-${lineIndex}`, dimColor: card.color === 'yellow'}, line)
+        )
+      )
+    )
   );
 
+  const helpOverlay = showHelp
+    ? create(
+        Box,
+        {
+          flexDirection: 'column',
+          borderStyle: 'double',
+          borderColor: 'cyan',
+          marginTop: 1,
+          padding: 1
+        },
+        create(Text, {color: 'cyan', bold: true}, 'Help overlay · press ? to hide'),
+        create(Text, null, 'Clicking cycles selections and scrolling the mouse wheel moves the output view.'),
+        create(Text, null, 'When a command is running you can type to feed stdin, Enter sends newline, Ctrl+C aborts.'),
+        create(Text, null, 'Layout now keeps Projects and Details side-by-side with Output below so nothing stretches.'),
+        create(Text, null, 'Use L to rerun the previous command and Shift + arrows or the mouse wheel to scroll the output window.')
+      )
+    : null;
+
   const headerHint = viewMode === 'detail'
     ? `Detail mode · 1-${Math.max(detailedIndexed.length, 1)} to execute, C: add custom commands, Enter: back to list, q: quit`
     : `Quick run · B/T/R to build/test/run, Enter: view details, q: quit`;
@@ -1152,25 +1294,24 @@ function Compass({rootPath}) {
         {flexDirection: 'column'},
         create(Text, {color: 'magenta', bold: true}, 'Project Compass'),
         create(Text, {dimColor: true}, loading ? 'Scanning workspaces…' : `${projectCountLabel} detected in ${rootPath}`),
-        create(Text, {color: 'cyan'}, kleur.italic('Art-coded build atlas'))
+        create(Text, {dimColor: true}, 'Mouse support: click to cycle, wheel to scroll output.')
       ),
       create(
         Box,
         {flexDirection: 'column', alignItems: 'flex-end'},
-        create(Text, {color: running ? 'yellow' : 'green'}, running ? 'Busy 🔁' : lastAction ? `Last: ${lastAction}` : 'Idle'),
+        create(Text, {color: running ? 'yellow' : 'green'}, running ? 'Busy streaming...' : lastAction ? `Last action · ${lastAction}` : 'Idle'),
         create(Text, {dimColor: true}, headerHint)
       )
     ),
     artBoard,
     create(
       Box,
-      {marginTop: 1},
+      {marginTop: 1, flexDirection: 'row', alignItems: 'stretch'},
       create(
         Box,
         {
-          flexDirection: 'column',
-          width: 60,
-          marginRight: 2,
+          flex: 1,
+          marginRight: 1,
           borderStyle: 'round',
           borderColor: 'magenta',
           padding: 1
@@ -1181,36 +1322,50 @@ function Compass({rootPath}) {
       create(
         Box,
         {
-          flexDirection: 'column',
-          width: 44,
-          marginRight: 2,
+          flex: 1,
           borderStyle: 'round',
           borderColor: 'cyan',
           padding: 1
         },
         create(Text, {bold: true, color: 'cyan'}, 'Details'),
         ...detailContent
+      )
+    ),
+    create(
+      Box,
+      {marginTop: 1, flexDirection: 'column'},
+      create(
+        Box,
+        {flexDirection: 'row', justifyContent: 'space-between'},
+        create(Text, {bold: true, color: 'yellow'}, `Output ${running ? '· Running' : ''}`),
+        create(Text, {dimColor: true}, logOffset ? `Scrolled ${logOffset} lines` : 'Live log view')
       ),
       create(
         Box,
         {
           flexDirection: 'column',
-          flexGrow: 1,
           borderStyle: 'round',
           borderColor: 'yellow',
-          padding: 1
+          padding: 1,
+          minHeight: OUTPUT_WINDOW_SIZE + 2,
+          overflow: 'hidden'
         },
-        create(Text, {bold: true, color: 'yellow'}, 'Output'),
-        create(
-          Box,
-          {flexDirection: 'column', marginTop: 1, height: 12, overflow: 'hidden'},
-          ...logNodes
-        )
+        ...logNodes
+      ),
+      create(
+        Text,
+        {dimColor: true, marginTop: 1},
+        running
+          ? 'Type to feed stdin, Enter submits, Ctrl+C aborts, Shift+Arrows or mouse wheel scrolls the buffer.'
+          : 'Run a command or press ? for extra help.'
       )
-    )
+    ),
+    helpSection,
+    helpOverlay
   );
 }
 
+
 function parseArgs() {
   const args = {};
   const tokens = process.argv.slice(2);