npm - termdeck-cli - Versions diffs - 1.0.3 → 2.0.3 - Mend

termdeck-cli 1.0.3 → 2.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/README.md CHANGED Viewed

@@ -1,234 +1,254 @@
-# termdeck
+<div align="center">
-A terminal dashboard (TUI) for juggling your local dev projects.
+# 🖥️ termdeck
-One screen lists your projects with a colour-coded status and blurb, and gives
-each one three actions:
+**A beautiful, terminal-based project dashboard to manage your local dev environments, services, and AI coding agents.**
-| CTA | What it does |
-| --- | --- |
-| **Dev Server** | runs `npm run dev` **inside termdeck** — stdout/stderr stream into the scrollable log pane below (no extra terminal window), then the localhost URL is detected and opened in your default browser |
-| **Editor** | opens a **brand new OS terminal window**, `cd`s into the project and runs `code .` |
-| **Agent** | opens a **brand new OS terminal window**, `cd`s into the project and runs `opencode` (placeholder — configurable) |
-Everything is keyboard driven *and* mouse driven: the three CTAs are clickable
-buttons, the project list is click-selectable, and the mouse wheel scrolls the
-logs.
+[![npm version](https://img.shields.io/npm/v/termdeck.svg)](https://www.npmjs.com/package/termdeck)
+[![license](https://img.shields.io/npm/l/termdeck.svg)](https://github.com/barigalasunil/termdeck/blob/main/LICENSE)
 ```
 +----------------------------------------------------------------------+
-| termdeck  4 projects · /home/you/Projects      ● 2 dev servers running
+| termdeck   14 projects · ~/dev/projects     ● 2 dev servers running   |
 +------------------------+---------------------------------------------+
 | projects               | selected project                            |
-| ● api      [Live]      | alpha   ● Working                           |
-| ● alpha    [Working]   | /home/you/Projects/alpha                    |
-| ○ blog     [Pending]   | marketing site                              |
-| ○ lab      [Experiment]| editor: code .   agent: opencode            |
-|                        | ● dev server running (pid 8123) → localhost |
+| ● api      [live]      | alpha   ● live                              |
+| ● alpha    [live]      | ~/dev/projects/alpha   main · 8a2f1 (2d ago)|
+| ○ blog     [exp]       | marketing site                              |
+| ○ lab      [scrap]     | ● dev server running (pid 8123) → localhost |
+|                        | cpu 3.2% · mem 214MB                       |
 +------------------------+---------------------------------------------+
-|                        | [d] Dev Server [e] Editor [a] Agent         |
-|                        +---------------------------------------------+
-|                        | dev server logs                             |
-|                        | 12:04:11 alpha [termdeck] $npm run dev      |
-|                        | 12:04:12 alpha ➜ Local: http://localhost:51 |
+| dev [r]  status [s]  search [/]  ...                                |
 +------------------------+---------------------------------------------+
-| ↑/↓ select  d dev  e editor  a agent  x stop  r reload  q quit       |
+| dev server logs                                                      |
+| 12:04:11 alpha [termdeck] $npm run dev                                |
+| 12:04:12 alpha ➜ Local: http://localhost:5173                       |
 +----------------------------------------------------------------------+
 ```
-## Install
+</div>
+---
+## ✨ Features
+- 🎯 **Centralized Dashboard** — See every project, its status (live, exp, pend, scrap), git state (branch, last commit), current process stats, and dev server state in one place.
+- ⚡ **In-Terminal Dev Servers** — Run `npm run dev` and stream the logs inside the dashboard. Auto-opens the browser. **Crash recovery** restarts a dead server up to 3 times.
+- 🚀 **One-Click External Tools** — Launch your editor or an AI coding agent (claude, codex, opencode, freebuff, kilocode) in a new terminal window, with agent logs tailed back into the dashboard.
+- 🔎 **Live Search & Filtering** — Type `/` to search projects by name; press `1`–`5` to filter by status chip.
+- ️ **Mouse & Keyboard Support** — Fully navigable with mouse clicks, Tab/Shift+Tab focus cycling, and keyboard shortcuts.
+- 💾 **Persistent, Self-Healing Config** — Interactive first-run setup saves `~/.termdeck-config.json`; the `--scan` wizard merges new projects without losing your custom agent configs.
+---
+## 📦 Installation
+### Global Install (Recommended)
 ```bash
 npm install -g termdeck
-termdeck
 ```
-Requires Node.js 16+ and a real terminal (macOS/Linux Terminal, Windows
-Terminal, iTerm, …). No Docker, no daemon, no background service.
+This installs the `termdeck` command anywhere.
-## First run
+### One-Off Run
-The first launch asks a few questions and remembers the answers in
-`~/.termdeck-config.json`:
+```bash
+npx termdeck
+```
-1. **Which directory holds your projects?** — pick from suggestions (common
-   folders like `~/Projects`, plus every drive letter on Windows) or type a path.
-2. **Which folders are projects?** — multi-select with <kbd>space</kbd>, confirm
-   with <kbd>enter</kbd>.
-3. **Status + description per folder** — `Experimental`, `Live`, `Working` or
-   `Pending`, plus a one line blurb.
+> **Note:** Requires Node.js 16+ and a real terminal (macOS/Linux Terminal, Windows Terminal, iTerm, etc.). No Docker, no daemon, no background service.
-Every later launch skips straight to the dashboard. Re-run it any time with
-`termdeck --setup` (existing answers are pre-filled as defaults).
+### Auto-Updates
-## Keys
+On every dashboard launch termdeck silently checks the npm registry for a newer version. When one exists it installs `termdeck@latest` in the background — no confirmation, no restart. Offline, slow or unreachable registries are ignored: you simply keep running the installed version.
-| Key | Action |
-| --- | --- |
-| <kbd>↑</kbd>/<kbd>↓</kbd>, <kbd>j</kbd>/<kbd>k</kbd> | select a project (or click it) |
-| <kbd>d</kbd> | start the dev server for the selection (or click **Dev Server**) |
-| <kbd>e</kbd> | open the editor in a new terminal window (or click **Editor**) |
-| <kbd>a</kbd> | open the agent in a new terminal window (or click **Agent**) |
-| <kbd>tab</kbd>, <kbd>shift</kbd>+<kbd>tab</kbd> | move keyboard focus to the buttons — a focused button lights up and answers to <kbd>space</kbd>/<kbd>enter</kbd> |
-| <kbd>x</kbd> | stop the selected project's dev server |
-| <kbd>r</kbd> | reload the config file from disk |
-| <kbd>PgUp</kbd>/<kbd>PgDn</kbd>, wheel | scroll the log pane (pauses following, shows how many lines arrived) |
-| <kbd>shift</kbd>+<kbd>G</kbd>, <kbd>end</kbd> | jump back to live logs |
-| <kbd>home</kbd> | jump to the start of the log history |
-| <kbd>q</kbd>, <kbd>ctrl</kbd>+<kbd>c</kbd> | quit — every dev server termdeck started is stopped first |
-Quitting while dev servers are running asks for a second <kbd>q</kbd> press.
-## CLI
+Disable the check on an individual run with:
+```bash
+termdeck --no-update
+```
+### Manual Upgrade
+```bash
+npm update -g termdeck
+# or, to force the very latest release:
+npm install -g termdeck@latest
 ```
-termdeck                launch the dashboard (runs setup on first use)
-termdeck --setup        re-run the setup wizard
-termdeck --reset        delete the config file, then run setup again
-termdeck --list         print the configured projects and exit (no TUI)
-termdeck --no-open      never auto-open the browser
-termdeck --help
+### Check the Installed Version
+```bash
 termdeck --version
+# or inspect the global install directly
+npm list -g termdeck
 ```
-## Config file
-`~/.termdeck-config.json` (override the path with the `TERMDECK_CONFIG`
-environment variable):
-```json
-{
-  "version": 1,
-  "root": "/home/you/Projects",
-  "devCommand": "npm run dev",
-  "editorCommand": "code .",
-  "agentCommand": "opencode",
-  "openBrowser": true,
-  "projects": [
-    {
-      "name": "alpha",
-      "path": "/home/you/Projects/alpha",
-      "status": "Working",
-      "info": "marketing site with a Next.js frontend"
-    }
-  ]
-}
+---
+## 🗑️ Uninstall
+To completely remove termdeck from your system:
+```bash
+npm uninstall -g termdeck
 ```
-The same keys can be set **per project** inside a `projects[]` entry
-(`devCommand`, `editorCommand`, `agentCommand`, `port`), which is handy when one
-repo needs `pnpm dev`, `npm start` or a fixed port. Editing the file by hand is
-fine — press <kbd>r</kbd> in the dashboard to reload it.
+This removes the global package and the `termdeck` command.
+Your project configuration at `~/.termdeck-config.json` is preserved.
+To delete the config file as well:
+```bash
+# macOS/Linux
+rm ~/.termdeck-config.json
+# Windows PowerShell
+Remove-Item ~\.termdeck-config.json
+```
+---
+## 🚀 First Run & Configuration
+On first launch termdeck detects that no `~/.termdeck-config.json` exists and runs an interactive setup wizard:
+1. **Which directory holds your projects?** — Pick from suggestions (common folders like `~/Projects`, `~/dev`, plus every drive letter on Windows) or type a path.
+2. **Which folders are projects?** — termdeck scans the directory and shows only folders that contain a `.git` directory or a `package.json` manifest. Multi-select with <kbd>Space</kbd>, confirm with <kbd>Enter</kbd>.
+3. **Per-project details** — For each project you pick, termdeck asks its status (`live`, `exp`, `pend` or `scrap`, default `exp`), the dev-server port (default `3000`) and the package manager (`npm`, `pnpm` or `yarn` — auto-detected from `pnpm-lock.yaml` / `yarn.lock`).
+Every later launch skips straight to the dashboard.
+> **Tip:** You can manually edit `~/.termdeck-config.json` if needed. Press <kbd>r</kbd> in the dashboard to reload.
-| Field | Meaning |
+---
+## ⌨️ Usage & Controls
+### CLI Flags
+| Command | What it does |
 | --- | --- |
-| `devCommand` | command run for the Dev Server CTA (default `npm run dev`) |
-| `editorCommand` | command run in the new editor terminal (default `code .`) |
-| `agentCommand` | command run in the new agent terminal (default `opencode`) |
-| `openBrowser` | set to `false` (or pass `--no-open`) to keep the browser closed |
-| `port` | fallback port used if the dev server never prints a URL (default `3000`) |
-| `status` | `Experimental` · `Live` · `Working` · `Pending` |
-## How each CTA works
-**Dev Server (in-app logs).** `cross-spawn` runs the dev command with `cwd` set
-to the project, `stdio: ['ignore','pipe','pipe']` and `FORCE_COLOR=0`, so nothing
-is attached to a terminal. Each stream is split into lines and pushed into the
-blessed-contrib `log` widget in the dashboard (batched every 120 ms — dev
-servers can emit hundreds of lines per second). Every line is scanned for a
-localhost URL (`http://localhost:5173/`, `0.0.0.0:3000`, `listening on port
-4200`, …); the first hit is normalised, and after a short delay the `open`
-package launches your default browser. If no URL shows up within ~9 seconds,
-termdeck assumes `http://localhost:<port || 3000>` and says so in the log pane.
-Processes are spawned detached on macOS/Linux and killed as a tree
-(`process.kill(-pid)` / `taskkill /T /F`), so a quit never leaves an orphaned
-Vite/Next server behind.
-**Editor / Agent (new terminal windows).** `cross-spawn` launches the OS
-terminal:
-- **macOS** — `osascript -e 'tell application "Terminal" … do script "cd … && code ."'`
-- **Windows** — `wt.exe -d "<dir>" cmd /k "code ."`, falling back to
-  `cmd /c start "" /D "<dir>" cmd.exe /k "code ."` when Windows Terminal is not
-  installed
-- **Linux** — the first emulator found on `PATH` out of `gnome-terminal`,
-  `konsole`, `xfce4-terminal`, `kitty`, `alacritty`, `wezterm`,
-  `x-terminal-emulator`, `xterm` (each gets `--working-directory`/`-e` with
-  `bash -lc` and `exec bash` so the window stays open)
-On Linux you can force a specific emulator with the `TERMDECK_TERMINAL`
-environment variable.
-## Linking locally (test before publishing)
-From the project folder:
+| `termdeck` | Launch the dashboard using the existing config (first run starts the wizard). |
+| `termdeck --demo` | Launch with 14 sample projects (great for trying it out). |
+| `termdeck --scan` | Re-run the interactive scanner: adds/updates projects in the config, merging with existing entries and preserving custom agent configs. |
+| `termdeck --no-auto-restart` | Disable dev-server crash recovery for this session only. |
+| `termdeck --reset` | Delete the config file and force a fresh first-run setup on the next launch. |
+| `termdeck --no-update` | Disable the background auto-updater. |
+| `termdeck --setup` | Re-run the setup wizard manually. |
+| `termdeck --list` | Print the configured projects as a table and exit (no TUI). |
+| `termdeck --no-open` | Do not auto-open the browser when a dev server starts. |
+### Keyboard Shortcuts
-```bash
-npm install          # install dependencies
-npm test             # unit + end-to-end dev server tests (no TUI needed)
-npm run smoke        # headless TUI smoke test: renders the dashboard, clicks a CTA
+| Key | Action |
+| --- | --- |
+| <kbd>↑</kbd> / <kbd>↓</kbd> or <kbd>j</kbd> / <kbd>k</kbd> | Navigate projects |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Cycle focus: project list → actions → output |
+| <kbd>Enter</kbd> or <kbd>Space</kbd> | Activate the focused button |
+| <kbd>r</kbd> / <kbd>d</kbd> | Run `npm run dev` for the selected project |
+| <kbd>e</kbd> | Open the project in your editor in a new terminal |
+| <kbd>c</kbd> | Open Claude in a new terminal |
+| <kbd>x</kbd> | Open Codex in a new terminal |
+| <kbd>o</kbd> | Open opencode in a new terminal |
+| <kbd>f</kbd> | Open freebuff in a new terminal |
+| <kbd>k</kbd> | Open kilocode in a new terminal |
+| <kbd>s</kbd> | Cycle the selected project's status |
+| <kbd>/</kbd> | Search projects by name (Enter commits, Esc cancels) |
+| <kbd>1</kbd>–<kbd>5</kbd> | Filter by status chip: all / live / exp / pend / scrap |
+| <kbd>Shift</kbd>+<kbd>X</kbd> | Stop the selected project's dev server |
+| <kbd>PgUp</kbd>/<kbd>PgDn</kbd>, mouse wheel | Scroll the dev server logs (<kbd>g</kbd> to follow the tail again) |
+| <kbd>q</kbd> | Quit (stops every dev server it started) |
-npm link             # symlinks this package into your global node_modules
-termdeck             # now runs from anywhere with your edits live
+> **Mouse Support:** All buttons and list items are fully clickable. Use the mouse wheel to scroll logs.
-# when you are done
-npm unlink -g termdeck
+---
+## ❓ FAQ
+**How do I disable auto-updates?**
+Pass `--no-update` when you launch the dashboard: `termdeck --no-update`. The npm registry is then never contacted and nothing is printed.
+**A dev server keeps restarting — how do I stop that?**
+termdeck restarts a crashed dev server up to 3 times, then gives up and logs the failure. If you would rather not have any crash recovery for a session, launch with `termdeck --no-auto-restart`.
+**Does my config get clobbered when I re-scan?**
+No. `termdeck --scan` (or the setup wizard on a machine that already has a config) merges: projects you didn't touch stay exactly as they are, projects you re-select get their new status/port/package manager, and hand-written per-project overrides such as custom agent commands are kept.
+---
+## 🛠️ Development & Contributing
+### Local Testing
+```bash
+git clone https://github.com/barigalasunil/termdeck.git
+cd termdeck
+npm install
+npm link        # symlink into global node_modules
+termdeck         # runs from anywhere with your edits live
 ```
-`npm link` creates a global `termdeck` shim that points at this directory, so
-code changes take effect immediately — no republishing. If you would rather not
-touch the global install, these work too:
+### Running Tests
 ```bash
-npm install -g .             # real global install from the folder
-node bin/termdeck.js         # run the entry point directly
-npm exec -- termdeck         # run via the local package
+npm test        # unit + end-to-end dev server tests (64/64 passing ✅)
+npm run smoke   # headless TUI smoke test
 ```
-Two tips while testing:
+The smoke test drives a headless blessed screen: it verifies the dashboard renders, the dev-server CTA starts a real fixture server and streams its logs into the log pane, and that stopping the server cleans up the child process.
-- Keep your real config safe by pointing at a throwaway one:
-  `TERMDECK_CONFIG=./scratch-config.json termdeck` (on Windows Git Bash use
-  `TERMDECK_CONFIG=./scratch-config.json node bin/termdeck.js`).
-- `termdeck --list` prints the parsed config without starting the TUI, which is
-  the quickest way to check that setup wrote what you expected.
+### Testing Auto-Updates
-When you are ready to publish:
+The updater reads its registry endpoint from `TERMDECK_REGISTRY_URL`, so you can point it at a local mock. In one terminal, serve a fake registry that always claims a newer version:
 ```bash
-npm pack --dry-run   # inspect exactly which files would be uploaded
-npm publish          # needs an npm account; the package name must be free
+node -e "require('http').createServer((q,s)=>{s.setHeader('content-type','application/json');s.end(JSON.stringify({version:'9.9.9'}))}).listen(4873)"
 ```
-The `bin` field in `package.json` plus the `#!/usr/bin/env node` shebang in
-`bin/termdeck.js` are what make the global `termdeck` command work.
+Then run termdeck with the mock enabled:
-## Troubleshooting
+```bash
+# macOS/Linux
+TERMDECK_REGISTRY_URL=http://127.0.0.1:4873/termdeck/latest termdeck
-| Symptom | Fix |
-| --- | --- |
-| `termdeck needs an interactive terminal` | first-run setup and the dashboard need a TTY. Use a real terminal, or `termdeck --list` |
-| Browser opens too early / too late | tune the port: the URL is only opened once it appears in the output. Silence your dev server's URL banner and termdeck falls back after ~9s |
-| "no terminal emulator found" | install one of the Linux terminals above or set `TERMDECK_TERMINAL` |
-| `opencode` not found in the new window | change `agentCommand` to whatever you use (`cursor .`, `claude`, `aider`, …) |
-| Log colours look plain | intentional: ANSI codes are stripped so the log pane stays readable in a terminal multiplexer |
-| Nothing appears when clicking | make sure you are *inside* the TUI window and the terminal reports mouse events (Windows Terminal, iTerm2, GNOME Terminal, VS Code all do) |
+# Windows PowerShell
+$env:TERMDECK_REGISTRY_URL="http://127.0.0.1:4873/termdeck/latest"; termdeck
+```
-## Development
+> The install always targets `@latest` on the **real** npm registry. Set the mock to your current version (e.g. `{"version":"2.0.0"}`) to exercise the "already up to date, no install" path, or use `--no-update` to skip the check entirely.
+### Releasing a Version
+```bash
+npm version patch     # 2.0.0 -> 2.0.1 (bug fixes)
+npm version minor     # adds backwards-compatible features
+npm version major     # breaking changes
+npm publish
 ```
-bin/termdeck.js     shebang shim -> src/index.js
-src/index.js        CLI flags, setup-or-dashboard decision
-src/config.js       ~/.termdeck-config.json + the inquirer wizard
-src/dashboard.js    the blessed/blessed-contrib TUI
-src/devServer.js    spawn + log streaming + URL detection + browser open
-src/terminal.js     OS-specific "new terminal window" plans
-src/logView.js      scrollable, follow-the-tail log pane
-src/util.js         ANSI stripping, URL parsing, which(), killTree()
-test/run.js         npm test — unit tests + a real npm run dev lifecycle
-test/smoke.js       npm run smoke — headless render + real mouse click on a CTA
+Publishing a higher version is what triggers the auto-update for everyone already running termdeck.
+### Unlink When Done
+```bash
+npm unlink -g termdeck
 ```
-## License
+> **Tip:** Use `TERMDECK_CONFIG=./scratch-config.json termdeck` to test without touching your real config.
+---
+## 📄 License
 MIT
+---
+<div align="center">
+**Built with ❤️ by [Sunil](https://github.com/barigalasunil)**
+[GitHub](https://github.com/barigalasunil/termdeck) · [npm](https://www.npmjs.com/package/termdeck)
+</div>

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "name": "termdeck-cli",
-  "version": "1.0.3",
-  "description": "A terminal dashboard for your local dev projects: start dev servers with in-app logs, open your editor, or launch a coding agent in a fresh terminal window.",
+  "version": "2.0.3",
+  "description": "Terminal project control: a multi-pane TUI to manage your local dev projects — dev servers, git state, process stats, and AI coding agents.",
   "keywords": [
     "cli",
     "tui",
@@ -9,23 +9,24 @@
     "blessed",
     "blessed-contrib",
     "dev-server",
-    "projects"
+    "projects",
+    "agents"
   ],
   "license": "MIT",
   "main": "src/index.js",
   "bin": {
-    "termdeck": "bin/termdeck.js"
+    "termdeck": "src/index.js"
   },
   "files": [
-    "bin",
     "src",
+    "sample-config.json",
     "README.md"
   ],
   "engines": {
     "node": ">=16"
   },
   "scripts": {
-    "start": "node bin/termdeck.js",
+    "start": "node src/index.js",
     "test": "node test/run.js",
     "smoke": "node test/smoke.js"
   },
@@ -34,6 +35,7 @@
     "blessed-contrib": "^4.11.0",
     "cross-spawn": "^7.0.3",
     "inquirer": "^8.2.6",
-    "open": "^8.4.2"
+    "open": "^8.4.2",
+    "pidusage": "^3.0.2"
   }
 }