[TEST] feat(cli): interactive menu for all commands

[skull463]

What changed

• Interactive menu — running bytebell-tinker (or the short bbtinker) with no arguments opens a grouped menu (Setup / Knowledge / Server / Insights). Arrow keys move, Enter runs.
• Menu loops — after a command or form finishes you land back on the menu, so you can move back and forth between options without relaunching.
• Navigation keys — q backs out of a sub-screen to the menu; Esc leaves the TUI. (On the text-entry screens Esc backs out instead, since q is a typed character there.)
• Configure LLM provider screen — switch OpenRouter/Ollama and set the API key + model without remembering config keys. Tab moves between fields (fixed a bug where focus was trapped on the API key and you couldn't reach/edit the Model field).
• Connect MCP clients entry — runs mcp install to register the bytebell MCP endpoint in your editors.
• Mode-aware setup form — when you pick Docker it shows the Mongo/Neo4j/Redis fields; when you pick Embedded it shows the SQLite/Ladybug/Queue paths. Esc returns to the menu.
• Centralized theme — a single accent colour (theme.ts) drives every screen and the plain-stdout output (spinners, tables, progress bars), so the whole CLI is themed consistently from one place. Accent is cyan.
• Renamed binary — bytebell-tinker (plus the short bbtinker alias) so this dev build doesn't collide with an installed bytebell that only prints help.
• Non-TUI bytebell entry — a third binary bytebell that shows commander help on bare invocation (no menu), keeping backward compatibility with scripts/aliases that expect bytebell to print subcommands.
• Shutdown without lsof — waitForServerStopped falls back to isAlive(pid) polling on resolved target PIDs when lsof is unavailable (common on minimal Linux images), instead of returning immediately.
• Fixes: shutdown finds the server by its listening port (a stale pid file no longer leaves it running); stats no longer crashes on older repo records; mcp stats auto-starts the server instead of erroring.
• Merged latest main (the setup wizard + embedded-mode refactor) and resolved the conflicts.

Why

bytebell with no arguments just printed help, so you had to remember every subcommand. The menu makes the CLI discoverable and lets you bounce between actions. The dedicated provider screen removes the most common config friction, and the shutdown/stats/mcp fixes address real failures hit while testing.

The third bytebell binary keeps the old behavior (help on bare invocation) for scripts while bytebell-tinker/bbtinker drive the interactive TUI. The shutdown lsof fallback prevents the CLI from falsely reporting a clean stop on hosts without lsof.

How to test

1. Check out this branch and install + link:

   bun install
   cd packages/cli && bun link && cd -

2. Open the menu:

   bbtinker

   Arrow through the groups; the cyan cursor wraps. Run a command, confirm you return to the menu (loop). Press q in a sub-screen to go back, Esc to leave.
3. bytebell non-TUI — run without arguments, confirm it prints help (not the menu):

   bytebell

4. Configure LLM provider → choose OpenRouter → Tab down to Model → type a model → Enter to save. Re-open to confirm it persisted.
5. Settings → Tab to Infrastructure, press ←/→: Docker shows Mongo/Neo4j/Redis, Embedded shows the SQLite/Ladybug/Queue paths.
6. Stats / MCP usage with the server stopped → it auto-starts the server and renders the table (no "Unable to connect").
7. Shutdown fix:

   bbtinker shutdown --keep-docker
   lsof -nP -iTCP:8080 -sTCP:LISTEN   # empty afterwards

Screenshots

Terminal render of the menu (cyan accent not shown in plain text):

╭──────────────────────────────────────────────────────────────╮
│  Bytebell Tinker                                               │
│  local knowledge engine · open-ir                              │
│                                                                │
│  SETUP                                                         │
│   ❯ ⚙  Configure LLM provider  switch openrouter/ollama · key  │
│     ⚙  Settings                infra config / setup form       │
│     ⧉  Connect MCP clients     register bytebell in your editors│
│  KNOWLEDGE                                                     │
│     ✚ Index  ⤓ Ingest  ↻ Pull  ≡ List  ✕ Delete               │
│  SERVER                                                        │
│     ▲ Boot   ■ Shutdown                                        │
│  INSIGHTS                                                      │
│     ▤ Stats   ◷ MCP usage                                     │
╰──────────────────────────────────────────────────────────────╯
   ↑ ↓  navigate    ⏎  run    esc  quit                   v0.0.0

Non-TUI bytebell help output:

Usage: bytebell [options] [command]

Bytebell Tinker — local knowledge engine TUI
...

[bharatsachya]

Pull Request Guide

Follow these conventions so every PR is easy to navigate, review, and merge.

---

1. Branch Naming

General rules

• Descriptive: use clear, concise names that describe the purpose of the branch.
• Lowercase only: no uppercase letters.
• Hyphens to separate words: no spaces, no underscores.
• No special characters: avoid !, @, #, $, %, etc.
• Always prefix with the type of work (see below).

Branch prefixes

Prefix	When to use	Example
feature/	New features or enhancements	feature/user-authentication
bugfix/	Bug fixes	bugfix/login-issue
hotfix/	Critical fixes that must ship immediately	hotfix/payment-gateway-error
improvement/	Non-feature improvements (refactors, perf)	improvement/refactor-auth-module
release/	Release prep	release/v1.2.0
chore/	Maintenance: dependencies, configs, tooling	chore/update-dependencies
docs/	Documentation-only changes	docs/update-readme

---

2. PR Title

Every PR title must start with a status tag followed by the branch purpose.

Status tags

Tag	Meaning
[WIP]	Work in progress — do not merge yet. Reviewers may skim but not approve.
[TEST]	Ready for review and testing. Feedback welcome; not yet merge-ready.
[DONE]	Reviewed, tested, and ready to merge.

Update the tag as the PR progresses — move from [WIP] → [TEST] → [DONE].

Examples

• [WIP] feature/user-authentication — initial Bitbucket OAuth wiring
• [TEST] bugfix/login-issue — fix wrong org routing on re-login
• [DONE] chore/update-dependencies — bump fastify to 5.6
• [DONE] docs/update-readme

---

3. PR Description

Every PR description must include these sections:

What changed

A clear bulleted list of the concrete changes. Not a copy of the commit log — a human-readable summary.

Why

The reason for the change. Link the ticket / issue / conversation that prompted it. If it's a bug fix, describe the bug.

How to test

Step-by-step instructions a reviewer can follow to verify the change end-to-end. Include:

• Commands to run
• Endpoints to hit / UI flows to exercise
• Expected results

Screenshots (frontend PRs only)

Required for any PR that touches UI. Include:

• Before screenshot of the current UI (omit for brand-new UI)
• After screenshot showing the PR's result
• For multi-state UIs (loading / empty / error / success), show each state
• For responsive changes, show both desktop and mobile widths

Use the GitHub image upload (drag and drop into the description box) — do not link to external image hosts.

---

4. Example PR Description

## What changed

- Added `CreatedByBadge` component shared between Feedback and Chats pages
- Role-gated the badge to org admins only via `useAuth` hook
- Added `user_role` to the login response so the frontend can determine admin status

## Why

Org admins need to see who authored each feedback/chat entry for accountability.
Regular users always see their own content, so the createdBy chip is redundant for them.

Linked issue: #142

## How to test

1. Log in as `admin_user@emai.com` (role: `admin`)
2. Open `http://localhost/deadbytes-org/feedback?page=1` — avatar chip should appear on rows with a `createdBy`
3. Open `http://localhost/deadbytes-org/chats?page=1` — same behaviour
4. Log in as a regular user — the chip should NOT appear on either page

## Screenshots

### Feedback page — admin view

[screenshot-admin-feedback.png]

### Feedback page — regular user view

[screenshot-user-feedback.png]

---

5. Checklist Before Marking [DONE]

• Branch name follows the naming rules above
• Title starts with a status tag
• Description has What / Why / How to test sections
• Screenshots attached (frontend PRs only)
• All CI checks pass (formatting, build, tests)
• Self-reviewed the diff — no leftover debug logs, commented-out code, or secrets
• Rebased against the target branch so the diff is clean

Thanks for keeping the review process fast and the git history readable.

Here you go this is template for PR description

[bharatsachya]

Also please resolve your conflicts

[bharatsachya]

1.Theme should be centralised and it should work for all the commands
2.Add a back command to go back and forth between options
3. replace bytebell with bytebell set as bytebell shows helper command

[bharatsachya]

Bytebell is still showing menu revert it back to older version

[bharatsachya]

findListenerPids() returns [] whenever lsof is missing or errors (by design, "degrade gracefully"). But waitForServerStopped() is built entirely on findListenerPids, so on a host without lsof it returns true immediately — stopServer sends SIGTERM, unlinks the pid file, and reports a clean stop without ever confirming the process is down. The old code waited for the pid file to vanish, which was weaker but at least waited. macOS (the stated platform) ships lsof, but the CLI is distributed cross-platform and minimal Linux images frequently lack it. Consider falling back to isAlive(pid)-polling on the resolved target pids when findListenerPids yields nothing.

[bharatsachya]

no you cannot change this