project-compass 1.0.5 → 1.0.8

package/README.md

@@ -7,7 +7,7 @@ Project Compass is a futuristic CLI navigator built with [Ink](https://github.co
 - 🔍 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 + 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.
+- 💡 A dedicated output row with an interactive stdin buffer, plus help tiles that stay in their own band; Shift+↑/↓ or mouse wheel scrolls logs, typing feeds stdin (Enter submits, Ctrl+C aborts), L reruns the last command, H hides the cards, 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.
 - 🧠 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.
@@ -29,14 +29,16 @@ project-compass [--dir /path/to/workspace]
 
 | Key | Action |
 | --- | --- |
-| ↑ / ↓ | Navigate the project list |
-| Enter | Toggle the detail view with icons, commands, frameworks, and info |
-| B / T / R | Quick build / test / run actions (when available) |
-| 1‑9 | Execute the numbered command inside the detail view |
+| ↑ / ↓ | 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 (Shift+arrows or mouse wheel) |
-| L | Rerun the last executed command |
+| Shift ↑ / ↓ | Scroll the output buffer (or use the mouse wheel) |
+| L | Rerun the most recent command |
 | ? | Toggle the help overlay with navigation tips |
+| h | Hide/show the navigation/help cards beneath the logs |
+| s | Toggle the structure guide listing the manifests per language |
+| Typing while running | Sends stdin to the running command (Enter submits, Ctrl+C aborts) |
 | Ctrl+C | Interrupt a running command (works while streaming output) |
 | Q | Quit |
 
@@ -72,7 +74,12 @@ Project Compass now opens with a rounded art board that shuffles your glyph row
 
 ## 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).
+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), 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; press H to hide/show those tiles if you need more space, S to open the structure guide that lists the manifest files for each language detection, `?` to open the overlay with extra tips, and L to rerun the previous command.
+
+## 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.
+
 
 ## Developer notes
 

package/package.json

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

@@ -764,6 +764,14 @@ async function discoverProjects(root) {
   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',
@@ -771,8 +779,11 @@ const ACTION_MAP = {
 };
 const ART_CHARS = ['▁', '▃', '▄', '▅', '▇'];
 const ART_COLORS = ['magenta', 'blue', 'cyan', 'yellow', 'red'];
-const OUTPUT_WINDOW_SIZE = 10;
+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) {
@@ -829,6 +840,9 @@ function Compass({rootPath}) {
   const [customMode, setCustomMode] = useState(false);
   const [customInput, setCustomInput] = useState('');
   const [config, setConfig] = useState(() => loadConfig());
+  const [showHelpCards, setShowHelpCards] = useState(true);
+  const [showStructureGuide, setShowStructureGuide] = useState(false);
+  const [stdinBuffer, setStdinBuffer] = useState('');
   const [showHelp, setShowHelp] = useState(false);
   const [recentRuns, setRecentRuns] = useState([]);
   const selectedProject = projects[selectedIndex] || null;
@@ -838,10 +852,17 @@ function Compass({rootPath}) {
   const addLog = useCallback((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;
+      const appended = [...prev, normalized];
+      const next = appended.length > 250 ? appended.slice(appended.length - 250) : appended;
+      setLogOffset((prevOffset) => {
+        const maxScroll = Math.max(0, next.length - OUTPUT_WINDOW_SIZE);
+        if (prevOffset === 0) {
+          return 0;
+        }
+        return Math.min(maxScroll, prevOffset + 1);
+      });
+      return next;
     });
-    setLogOffset(0);
   }, []);
 
   const detailCommands = useMemo(() => buildDetailCommands(selectedProject, config), [selectedProject, config]);
@@ -901,6 +922,7 @@ function Compass({rootPath}) {
       addLog(kleur.red(`✗ ${commandLabel} failed: ${error.shortMessage || error.message}`));
     } finally {
       setRunning(false);
+      setStdinBuffer('');
       runningProcessRef.current = null;
     }
   }, [addLog, running, selectedProject]);
@@ -952,7 +974,7 @@ function Compass({rootPath}) {
     setCustomInput('');
   }, [customInput, selectedProject, handleAddCustomCommand, addLog]);
 
-  useInput((input, key) => {
+    useInput((input, key) => {
     if (customMode) {
       if (key.return) {
         handleCustomSubmit();
@@ -973,6 +995,16 @@ function Compass({rootPath}) {
       return;
     }
 
+    const normalizedInput = input?.toLowerCase();
+    if (normalizedInput === 'h') {
+      setShowHelpCards((prev) => !prev);
+      return;
+    }
+    if (normalizedInput === 's') {
+      setShowStructureGuide((prev) => !prev);
+      return;
+    }
+
     const scrollLogs = (delta) => {
       setLogOffset((prev) => {
         const maxScroll = Math.max(0, logLines.length - OUTPUT_WINDOW_SIZE);
@@ -980,47 +1012,43 @@ function Compass({rootPath}) {
       });
     };
 
-    if (key.mouse) {
-      if (key.mouse === 'left' && projects.length > 0) {
-        setSelectedIndex((prev) => (prev + 1) % projects.length);
-      } else if (key.mouse === 'scrollUp' || key.mouse === 'wheelUp') {
-        scrollLogs(1);
-      } else if (key.mouse === 'scrollDown' || key.mouse === 'wheelDown') {
-        scrollLogs(-1);
-      }
-      return;
-    }
-
     if (running && runningProcessRef.current) {
       if (key.ctrl && input === 'c') {
         runningProcessRef.current.kill('SIGINT');
+        setStdinBuffer('');
         return;
       }
       if (key.return) {
         runningProcessRef.current.stdin?.write('\n');
+        setStdinBuffer('');
+        return;
+      }
+      if (key.backspace) {
+        runningProcessRef.current.stdin?.write('\x08');
+        setStdinBuffer((prev) => prev.slice(0, -1));
         return;
       }
       if (input) {
         runningProcessRef.current.stdin?.write(input);
+        setStdinBuffer((prev) => prev + input);
       }
       return;
     }
 
     if (key.shift && key.upArrow) {
-      const maxScroll = Math.max(0, logLines.length - OUTPUT_WINDOW_SIZE);
-      setLogOffset((prev) => Math.min(maxScroll, prev + 1));
+      scrollLogs(1);
       return;
     }
     if (key.shift && key.downArrow) {
-      setLogOffset((prev) => Math.max(0, prev - 1));
+      scrollLogs(-1);
       return;
     }
 
-    if (input === '?') {
+    if (normalizedInput === '?') {
       setShowHelp((prev) => !prev);
       return;
     }
-    if (input === 'l' && lastCommandRef.current) {
+    if (normalizedInput === 'l' && lastCommandRef.current) {
       runProjectCommand(lastCommandRef.current.commandMeta, lastCommandRef.current.project);
       return;
     }
@@ -1040,26 +1068,26 @@ function Compass({rootPath}) {
       setViewMode((prev) => (prev === 'detail' ? 'list' : 'detail'));
       return;
     }
-    if (input === 'q') {
+    if (normalizedInput === 'q') {
       exit();
       return;
     }
-    if (input === 'c' && viewMode === 'detail' && selectedProject) {
+    if (normalizedInput === 'c' && viewMode === 'detail' && selectedProject) {
       setCustomMode(true);
       setCustomInput('');
       return;
     }
-    if (ACTION_MAP[input]) {
-      const commandMeta = selectedProject?.commands?.[ACTION_MAP[input]];
+    const actionKey = normalizedInput && ACTION_MAP[normalizedInput];
+    if (actionKey) {
+      const commandMeta = selectedProject?.commands?.[actionKey];
       runProjectCommand(commandMeta, selectedProject);
       return;
     }
-    if (viewMode === 'detail' && detailShortcutMap.has(input)) {
-      runProjectCommand(detailShortcutMap.get(input), selectedProject);
+    if (viewMode === 'detail' && normalizedInput && detailShortcutMap.has(normalizedInput)) {
+      runProjectCommand(detailShortcutMap.get(normalizedInput), selectedProject);
     }
   });
-
-  const projectRows = [];
+const projectRows = [];
   if (loading) {
     projectRows.push(create(Text, {dimColor: true}, 'Scanning projects…'));
   }
@@ -1213,60 +1241,86 @@ function Compass({rootPath}) {
   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))
+    ? visibleLogs.map((line, index) => create(Text, {key: index}, line))
     : [create(Text, {dimColor: true}, 'Logs will appear here once you run a command.')];
 
-  const helpCards = [
+  
+  // Using global SCHEMA_GUIDE
+
+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'
+        '↑/↓ move projects, Enter toggles detail view',
+        'Shift+arrows scroll logs',
+        'H hides/shows cards, ? opens overlay'
       ]
     },
     {
       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'
+        'B/T/R runs build/test/run quickly',
+        '1-9 execute detail commands',
+        'L reruns last command, Ctrl+C aborts',
+        'Type while 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.']
+      body: [
+        recentRuns.length ? `${recentRuns.length} runs recorded` : 'No runs yet · start with B/T/R',
+        'Press S for structure guide when you doubt the project layout'
+      ]
     }
   ];
 
-  const helpSection = create(
-    Box,
-    {marginTop: 1, flexDirection: 'row', justifyContent: 'space-between'},
-    ...helpCards.map((card, index) =>
-      create(
+  const helpSection = showHelpCards
+    ? create(
+        Box,
+        {marginTop: 1, flexDirection: 'row', justifyContent: 'space-between', flexWrap: 'wrap'},
+        ...helpCards.map((card, index) =>
+          create(
+            Box,
+            {
+              key: card.label,
+              flexGrow: 1,
+              flexBasis: 0,
+              minWidth: HELP_CARD_MIN_WIDTH,
+              marginRight: index < helpCards.length - 1 ? 1 : 0,
+              marginBottom: 1,
+              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)
+            )
+          )
+        )
+      )
+    : create(Text, {dimColor: true, marginTop: 1}, 'Help cards hidden · press H to show navigation, command flow, and recent runs.');
+
+  const structureGuide = showStructureGuide
+    ? create(
         Box,
         {
-          key: card.label,
-          flexGrow: 1,
-          flexBasis: 0,
-          marginRight: index < helpCards.length - 1 ? 1 : 0,
+          flexDirection: 'column',
           borderStyle: 'round',
-          borderColor: card.color,
+          borderColor: 'blue',
+          marginTop: 1,
           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)
-        )
+        create(Text, {color: 'cyan', bold: true}, 'Project structure guide · press S to hide'),
+        ...SCHEMA_GUIDE.map((entry) =>
+          create(Text, {key: entry.type, dimColor: true}, `• ${entry.icon} ${entry.label}: ${entry.files.join(', ')}`)
+        ),
+        create(Text, {dimColor: true, marginTop: 1}, 'SCHEMAS describe the manifests that trigger each language type.')
       )
-    )
-  );
+    : null;
 
   const helpOverlay = showHelp
     ? create(
@@ -1279,16 +1333,18 @@ function Compass({rootPath}) {
           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.')
+        create(Text, null, 'Shift+arrows scroll the output buffer.'),
+        create(Text, null, 'Run commands and type to feed stdin (Enter submits, Ctrl+C aborts).'),
+        create(Text, null, 'H hides/shows the navigation cards, S shows structure tips, and L reruns the previous command.'),
+        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).')
       )
     : null;
 
+  const toggleHint = showHelpCards ? 'H hides the help cards' : '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`
-    : `Quick run · B/T/R to build/test/run, Enter: view details, q: quit`;
+    ? `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`;
 
   return create(
     Box,
@@ -1301,7 +1357,7 @@ 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, {dimColor: true}, 'Mouse support: click to cycle, wheel to scroll output.')
+        create(Text, {dimColor: true}, 'Use keyboard arrows to navigate, ? for help.')
       ),
       create(
         Box,
@@ -1313,14 +1369,14 @@ function Compass({rootPath}) {
     artBoard,
     create(
       Box,
-      {marginTop: 1, flexDirection: 'row', alignItems: 'stretch', width: '100%', flexWrap: 'nowrap'},
+      {marginTop: 1, flexDirection: 'row', alignItems: 'stretch', width: '100%', flexWrap: 'wrap'},
       create(
         Box,
         {
           flexGrow: 1,
           flexBasis: 0,
           flexShrink: 1,
-          minWidth: 28,
+          minWidth: PROJECTS_MIN_WIDTH,
           marginRight: 1,
           borderStyle: 'round',
           borderColor: 'magenta',
@@ -1335,10 +1391,11 @@ function Compass({rootPath}) {
           flexGrow: 1.3,
           flexBasis: 0,
           flexShrink: 1,
-          minWidth: 36,
+          minWidth: DETAILS_MIN_WIDTH,
           borderStyle: 'round',
           borderColor: 'cyan',
-          padding: 1
+          padding: 1,
+          flexDirection: 'column'
         },
         create(Text, {bold: true, color: 'cyan'}, 'Details'),
         ...detailContent
@@ -1369,14 +1426,26 @@ function Compass({rootPath}) {
         ...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.'
+        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(
+        Box,
+        {
+          marginTop: 1,
+          flexDirection: 'row',
+          borderStyle: 'round',
+          borderColor: running ? 'green' : 'gray',
+          padding: 1
+        },
+        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')
       )
     ),
     helpSection,
+    structureGuide,
     helpOverlay
   );
 }