@rotorsoft/gent 1.16.0 → 1.17.1

package/README.md

@@ -1,14 +1,15 @@
 # @rotorsoft/gent
 
-AI-powered GitHub workflow CLI - leverage AI (Claude, Gemini, or Codex) to create tickets, implement features, and manage PRs.
+AI-powered GitHub workflow tool - leverage AI (Claude, Gemini, or Codex) to create tickets, implement features, and manage PRs from an interactive dashboard.
 
 ## Overview
 
-`gent` is a command-line tool that integrates AI with GitHub to automate your development workflow:
+`gent` provides an interactive dashboard that integrates AI with GitHub to automate your development workflow. Just run `gent` to launch:
 
-- **Create AI-enhanced tickets** - Describe what you need, the AI generates detailed GitHub issues with proper labels
-- **Implement with AI** - Pick a ticket and let the AI implement it with automatic branch management
-- **Track progress** - Maintain a progress log for context across AI sessions
+- **Dashboard at a glance** - See your current ticket, branch, PR, and commits in one view
+- **Context-aware actions** - The dashboard adapts to your workflow state with relevant shortcuts
+- **Create AI-enhanced tickets** - Describe what you need, the AI generates detailed GitHub issues
+- **Implement with AI** - Select a ticket and let the AI implement it with automatic branch management
 - **Create smart PRs** - Generate AI-enhanced pull requests with proper descriptions
 - **Iterate on feedback** - Address PR review comments with AI assistance
 
@@ -32,7 +33,7 @@ Verify prerequisites:
 gh auth status    # Should show authenticated
 claude --version  # Should show version (if using Claude)
 gemini --version  # Should show version (if using Gemini)
-codex --version  # Should show version (if using Codex)
+codex --version   # Should show version (if using Codex)
 ```
 
 ## Quick Start
@@ -57,97 +58,167 @@ gent setup-labels
 
 Creates workflow labels (`ai-ready`, `ai-in-progress`, etc.) and category labels.
 
-### 3. Create a ticket
+### 3. Launch the dashboard
 
 ```bash
-gent create "Add user authentication with JWT tokens"
+gent
 ```
 
-The AI will:
-- Generate a detailed issue with technical context
-- Infer appropriate labels (type, priority, risk, area)
-- Create the issue on GitHub with `ai-ready` label
+The dashboard is your primary interface. From here you can create tickets, switch between issues, run AI implementations, commit, push, and create PRs - all with single-key shortcuts.
 
-### 4. Implement a ticket
+## Dashboard
 
-```bash
-# Pick a specific issue
-gent run 123
+Running `gent` launches an interactive dashboard that shows your current workflow at a glance:
 
-# Or auto-select highest priority ai-ready issue
-gent run --auto
+```
+┌ gent v1.17.0 ────────────────────────────────────────┐
+│ Provider: Claude                                     │
+│ GitHub:   authenticated                              │
+├ Ticket ──────────────────────────────────────────────┤
+│ · #47  Add interactive TUI interface                 │
+│   IN PROGRESS  type:feature  priority:high  area:ui  │
+├ Branch ──────────────────────────────────────────────┤
+│ · ro/feature-47-add-interactive-tui                  │
+│   3 ahead  ·  ● uncommitted  ·  ● unpushed           │
+├ Pull Request ────────────────────────────────────────┤
+│   No PR created                                      │
+├ Commits ─────────────────────────────────────────────┤
+│ · feat: add TUI state aggregation                    │
+│ · feat: add TUI display components                   │
+├──────────────────────────────────────────────────────┤
+│ new  commit  push  pr  run  list  refresh  ai  quit  │
+└──────────────────────────────────────────────────────┘
 ```
 
-The AI will:
-- Create a feature branch
-- Update labels to `ai-in-progress`
-- Implement the feature following your `AGENT.md` instructions
-- Run validation commands
-- Create a commit
-- Update labels to `ai-completed`
+### Dashboard Panels
 
-### 5. Create a pull request
+- **Settings** - Shows AI provider, GitHub auth status, and update notifications
+- **Ticket** - Current issue with labels, priority, and workflow status badges
+- **Branch** - Current branch with sync status (ahead/uncommitted/unpushed/synced)
+- **Pull Request** - PR state (open/draft/merged/closed), review decision, and actionable feedback count
+- **Commits** - Recent commits on the current branch
+- **Hint** - Contextual suggestion based on your workflow state
 
-```bash
-gent pr
-```
+### Keyboard Shortcuts
 
-The AI will:
-- Generate a PR description from commits and linked issue
-- Include "Closes #" reference
-- Create the PR on GitHub
+The dashboard shows only the actions relevant to your current context:
 
-### 6. Address review feedback
+| Key | Action | When Available |
+|-----|--------|----------------|
+| `n` | New ticket | Always |
+| `c` | Commit changes | Uncommitted changes on feature branch |
+| `s` | Push (send) to remote | Unpushed commits on feature branch |
+| `p` | Create PR | Feature branch with commits, no PR yet |
+| `r` | Run AI implementation | Feature branch with linked issue, PR not merged |
+| `l` | List and switch tickets | Always |
+| `f` | Refresh dashboard | Always |
+| `a` | Switch AI provider | Always |
+| `q` | Quit | Always |
 
-After reviewers leave comments on your PR:
+### Context-Aware Behavior
 
-```bash
-gent fix
-```
+The dashboard adapts to your current state:
 
-The AI will:
-- Fetch all review comments and threads from the PR
-- Filter to show only feedback since your last commit
-- Present a summary of actionable feedback
-- Re-run implementation with review context
-- Auto-reply to addressed feedback comments
+- **On main branch** - Shows "ready to start new work"; use `n` to create a ticket or `l` to pick an existing one
+- **Uncommitted changes** - Hints to commit before creating a PR
+- **No PR yet** - Offers to create a pull request after commits are pushed
+- **PR with review feedback** - Shows actionable comment count and hints to address feedback
+- **UI changes with Playwright** - Notes that video capture is available
 
-Repeat `gent fix` as needed until the PR is approved.
+### Modal Dialogs
 
-## Dashboard
+Actions that need input (commit, list, create, switch provider) open floating modal dialogs over the dashboard. Modals support:
 
-Running `gent` with no arguments launches a dashboard that shows your current workflow at a glance:
+- **Select** - Arrow keys to navigate, Enter to confirm, Escape to cancel
+- **Confirm** - y/n to confirm or cancel
+- **Input** - Type text, Enter to submit, Escape to cancel
+- **Multiline input** - For ticket descriptions; Enter for newline, Ctrl+S to submit
 
-```
- gent v2.0.0                                     Claude · gh
+### Typical Workflow from the Dashboard
 
-┌ Ticket ──────────────────────────────────────────────┐
-│ #47  Add interactive TUI interface                   │
-│  IN PROGRESS   type:feature  priority:high  area:ui  │
-├ Branch ──────────────────────────────────────────────┤
-│ ro/feature-47-add-interactive-tui                    │
-│ 3 ahead  ·  ● uncommitted  ·  ● unpushed            │
-├ Pull Request ────────────────────────────────────────┤
-│ No PR created                                        │
-├ Commits ─────────────────────────────────────────────┤
-│ feat: add TUI state aggregation                      │
-│ feat: add TUI display components                     │
-└──────────────────────────────────────────────────────┘
+1. Press `n` to create a new ticket (describe the feature in the multiline input)
+2. Press `l` to list tickets and switch to the new one (creates a branch automatically)
+3. Press `r` to run AI implementation (opens an interactive AI session)
+4. Press `c` to commit (choose AI-generated or manual commit message)
+5. Press `s` to send (push) to remote
+6. Press `p` to create a pull request
+7. After review feedback, press `r` again to address comments (review context is included automatically)
 
-  c  commit    p  create pr    r  continue impl    q  quit
- Commit your changes before creating a PR
+## Workflow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                          GENT WORKFLOW                          │
+└─────────────────────────────────────────────────────────────────┘
+
+     ┌──────────┐    n (new)        ┌──────────┐
+     │   Idea   │ ─────────────────>│  Issue   │
+     └──────────┘                   │ ai-ready │
+                                    └────┬─────┘
+                                         │
+                                    l (list) → select
+                                         │
+                                         v
+                                    ┌──────────┐
+                                    │  Branch  │
+                                    │ created  │
+                                    └────┬─────┘
+                                         │
+                                    r (run)
+                                         │
+                                         v
+                                    ┌──────────┐
+                                    │  Issue   │
+                                    │ai-complete│
+                                    └────┬─────┘
+                                         │
+                                    c (commit) → s (send) → p (pr)
+                                         │
+                                         v
+                                    ┌──────────┐
+                                    │   PR     │
+                                    │ created  │
+                                    └────┬─────┘
+                                         │
+                                    Human review
+                                         │
+                              ┌──────────┴──────────┐
+                              │                     │
+                         Changes                Approved
+                         requested                  │
+                              │                     │
+                         r (run)                    │
+                              │                     │
+                              v                     │
+                         ┌──────────┐               │
+                         │   AI     │               │
+                         │  fixes   │───────────────┤
+                         └────┬─────┘               │
+                              │                     │
+                              └─── (repeat if needed)
+                                                    │
+                                               Merge PR
+                                                    │
+                                                    v
+                                               ┌──────────┐
+                                               │  Issue   │
+                                               │  closed  │
+                                               └──────────┘
 ```
 
-The dashboard adapts to your current context:
-- **On main branch** - offers to create new tickets or implement open issues
-- **Uncommitted changes** - prompts to commit before other actions
-- **No PR yet** - offers to create a pull request
-- **PR with review feedback** - offers to fix review comments
-- **UI changes with Playwright** - offers to record demo videos
+## CLI Reference
+
+All dashboard actions map to CLI commands that can also be run directly. This is useful for scripting, CI pipelines, or if you prefer a command-driven workflow.
 
-You can also launch it explicitly with `gent ui`.
+### `gent`
 
-## Commands
+Launch the interactive dashboard (default when no command is given).
+
+```bash
+gent
+# or explicitly
+gent ui
+```
 
 ### `gent init`
 
@@ -177,11 +248,11 @@ Creates labels in these categories:
 
 ### `gent create <description>`
 
-Create an AI-enhanced GitHub issue.
+Create an AI-enhanced GitHub issue (dashboard: `n`).
 
 ```bash
 gent create "Add dark mode toggle to settings page"
-gent create "Fix login bug" --provider gemini   # Use specific AI provider
+gent create "Fix login bug" --provider gemini
 ```
 
 Options:
@@ -190,7 +261,7 @@ Options:
 
 ### `gent list`
 
-List GitHub issues by label/status.
+List and switch between GitHub issues (dashboard: `l`).
 
 ```bash
 gent list                          # Show ai-ready issues
@@ -206,21 +277,19 @@ Options:
 
 ### `gent run [issue-number]`
 
-Run AI to implement a GitHub issue.
+Run AI to implement a GitHub issue (dashboard: `r`).
 
 ```bash
 gent run 123                   # Implement issue #123
-gent run --auto                # Auto-select highest priority ai-ready issue
 gent run 123 --provider gemini # Use specific AI provider
 ```
 
 Options:
-- `-a, --auto` - Auto-select highest priority ai-ready issue
 - `-p, --provider <provider>` - AI provider to use (`claude`, `gemini`, or `codex`)
 
 ### `gent pr`
 
-Create an AI-enhanced pull request.
+Create an AI-enhanced pull request (dashboard: `p`).
 
 ```bash
 gent pr                      # Create PR
@@ -254,7 +323,7 @@ Options:
 
 ### `gent status`
 
-Show current workflow status.
+Show current workflow status (useful for scripting and debugging).
 
 ```bash
 gent status
@@ -269,18 +338,6 @@ Displays:
 - PR status
 - Suggested actions
 
-### `gent ui`
-
-Launch the interactive dashboard. Also available by running `gent` with no arguments.
-
-```bash
-gent ui
-# or simply
-gent
-```
-
-The dashboard displays panels for Ticket, Branch, Pull Request, and Commits with context-aware keyboard shortcuts at the bottom. Actions refresh the dashboard automatically after completion.
-
 ## Configuration
 
 ### .gent.yml
@@ -360,68 +417,6 @@ Append-only log that tracks AI implementation sessions. Each entry includes:
 
 This provides context for future AI sessions and human reviewers.
 
-## Workflow
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                          GENT WORKFLOW                          │
-└─────────────────────────────────────────────────────────────────┘
-
-     ┌──────────┐    gent create    ┌──────────┐
-     │   Idea   │ ─────────────────>│  Issue   │
-     └──────────┘                   │ ai-ready │
-                                    └────┬─────┘
-                                         │
-                                    gent run
-                                         │
-                                         v
-                                    ┌──────────┐
-                                    │  Branch  │
-                                    │ created  │
-                                    └────┬─────┘
-                                         │
-                                    AI implements
-                                         │
-                                         v
-                                    ┌──────────┐
-                                    │  Issue   │
-                                    │ai-complete│
-                                    └────┬─────┘
-                                         │
-                                    gent pr
-                                         │
-                                         v
-                                    ┌──────────┐
-                                    │   PR     │
-                                    │ created  │
-                                    └────┬─────┘
-                                         │
-                                    Human review
-                                         │
-                              ┌──────────┴──────────┐
-                              │                     │
-                         Changes                Approved
-                         requested                  │
-                              │                     │
-                         gent fix                   │
-                              │                     │
-                              v                     │
-                         ┌──────────┐               │
-                         │   AI     │               │
-                         │  fixes   │───────────────┤
-                         └────┬─────┘               │
-                              │                     │
-                              └─── (repeat if needed)
-                                                    │
-                                               Merge PR
-                                                    │
-                                                    v
-                                               ┌──────────┐
-                                               │  Issue   │
-                                               │  closed  │
-                                               └──────────┘
-```
-
 ## Label Conventions
 
 ### Workflow Status
@@ -473,7 +468,7 @@ Examples:
 The author is derived from:
 1. `GENT_AUTHOR` environment variable (if `author_source: env`)
 2. `git config user.initials` (if set)
-3. Initials from `git config user.name` (e.g., "John Doe" → "jd")
+3. Initials from `git config user.name` (e.g., "John Doe" -> "jd")
 
 ## Environment Variables
 
@@ -481,12 +476,15 @@ The author is derived from:
 |----------|-------------|
 | `GENT_AUTHOR` | Override author initials for branch naming |
 | `GENT_AI_PROVIDER` | Override AI provider (`claude`, `gemini`, or `codex`) |
+| `GENT_SKIP_UPDATE_CHECK` | Set to `1` to disable update notifications |
 | `DEBUG` | Enable debug output |
 
 ## Tips
 
 ### Writing Good Descriptions
 
+When creating tickets (via `n` in the dashboard or `gent create`):
+
 ```bash
 # Good - specific and actionable
 gent create "Add password reset functionality with email verification"
@@ -518,23 +516,31 @@ If the AI gets stuck (`ai-blocked` label):
 
 ### PR Review Iteration
 
-The `gent fix` command streamlines the review cycle by allowing you to address feedback iteratively. It's particularly useful when you have multiple reviewers or several rounds of changes. The command intelligently ignores feedback you've already addressed in previous commits, keeping the AI focused only on what's currently pending.
+After receiving review feedback, press `r` in the dashboard (or run `gent fix` from the CLI) to address comments. The AI automatically includes review context and only focuses on new feedback since your last commit. Unresolved threads are always included regardless of age.
 
 ```bash
-# After creating a PR and receiving review feedback
+# CLI equivalent for review iteration
 gent fix                    # AI addresses the feedback
 git push                    # Push the fixes
 
-# If more feedback comes in later or new reviewers add comments
-gent fix                    # AI only focuses on the NEW comments
+# If more feedback comes in
+gent fix                    # AI only focuses on NEW comments
 git push                    # Push again
 ```
 
-The command intelligently:
-- Only shows feedback newer than your last commit to avoid redundant work.
-- Always includes unresolved review threads to ensure every concern is addressed.
-- Auto-replies to feedback comments after fixes are committed, closing the loop with reviewers.
-- Works with any AI provider (Claude, Gemini, Codex).
+### Dashboard vs CLI
+
+The dashboard (`gent`) is the recommended way to use gent. It provides:
+- A unified view of your workflow state
+- Context-aware actions (only shows what's relevant)
+- Modal dialogs for input (no need to remember command flags)
+- Automatic refresh after actions
+
+CLI commands are available for:
+- Scripting and automation (`gent create --yes "..."`)
+- CI/CD pipelines
+- Users who prefer a command-driven workflow
+- Advanced filtering (`gent list --status all --label priority:high`)
 
 ## Contributing
 

package/dist/index.js

@@ -2221,7 +2221,7 @@ import { homedir } from "os";
 // package.json
 var package_default = {
   name: "@rotorsoft/gent",
-  version: "1.16.0",
+  version: "1.17.1",
   description: "AI-powered GitHub workflow CLI - leverage AI (Claude, Gemini, or Codex) to create tickets, implement features, and manage PRs",
   keywords: [
     "cli",
@@ -2786,13 +2786,13 @@ function getAvailableActions(state) {
       actions.push({ id: "commit", label: "commit", shortcut: "c" });
     }
     if (state.hasUnpushedCommits && state.commits.length > 0) {
-      actions.push({ id: "push", label: "push", shortcut: "p" });
+      actions.push({ id: "push", label: "push", shortcut: "s" });
     }
     if (!state.pr && state.commits.length > 0) {
-      actions.push({ id: "pr", label: "pr", shortcut: "r" });
+      actions.push({ id: "pr", label: "pr", shortcut: "p" });
     }
     if (state.issue && state.pr?.state !== "merged") {
-      actions.push({ id: "run", label: "run", shortcut: "u" });
+      actions.push({ id: "run", label: "run", shortcut: "r" });
     }
   }
   actions.push({ id: "list", label: "list", shortcut: "l" });
@@ -2907,14 +2907,14 @@ var shortcutColors = [
   chalk3.red.bold
 ];
 function formatAction(a, color) {
-  const key = a.shortcut;
-  const idx = a.label.indexOf(key);
+  const idx = a.label.indexOf(a.shortcut);
+  const styledKey = color(chalk3.underline(a.shortcut));
   if (idx >= 0) {
     const before = a.label.slice(0, idx);
-    const after = a.label.slice(idx + key.length);
-    return chalk3.dim(before) + color(key) + chalk3.dim(after);
+    const after = a.label.slice(idx + a.shortcut.length);
+    return chalk3.dim(before) + styledKey + chalk3.dim(after);
   }
-  return color(key) + " " + chalk3.dim(a.label);
+  return styledKey + " " + chalk3.dim(a.label);
 }
 function formatCommandBar(actions, w) {
   const parts = actions.map((a, i) => {
@@ -2971,14 +2971,22 @@ function buildDashboardLines(state, actions, hint, refreshing, versionCheck) {
   out(topRow(titleLabel, w));
   renderSettingsTo(state, w, out, versionCheck);
   if (!state.isGitRepo) {
-    out(row(chalk3.red("Not a git repository"), w));
-    out(row(chalk3.dim("Run gent init in a git repo to get started"), w));
+    out(row(chalk3.yellow("Not a git repository"), w));
+    out(row(chalk3.dim("Navigate to a git repository to get started"), w));
+    out(divRow(w));
+    for (const line of formatCommandBar(actions, w)) {
+      out(row(line, w));
+    }
     out(botRow(w));
     return lines;
   }
   if (!state.isGhAuthenticated) {
     out(row(chalk3.red("GitHub CLI not authenticated"), w));
     out(row(chalk3.dim("Run: gh auth login"), w));
+    out(divRow(w));
+    for (const line of formatCommandBar(actions, w)) {
+      out(row(line, w));
+    }
     out(botRow(w));
     return lines;
   }
@@ -3138,7 +3146,7 @@ function buildModalFrame(title, contentLines, footerText, width) {
 function isSeparator(entry) {
   return "separator" in entry;
 }
-function buildSelectContent(items, selectedIndex, maxWidth) {
+function buildSelectContent(items, selectedIndex, maxWidth, currentIndex) {
   const lines = [];
   let selectableIdx = 0;
   for (const item of items) {
@@ -3146,12 +3154,12 @@ function buildSelectContent(items, selectedIndex, maxWidth) {
       lines.push(chalk4.dim(item.separator));
     } else {
       const isSelected = selectableIdx === selectedIndex;
+      const isCurrent = currentIndex != null && selectableIdx === currentIndex;
       const prefix = isSelected ? chalk4.cyan.bold("> ") : "  ";
       const bullet = chalk4.dim("\xB7 ");
       const label = truncateAnsi(item.name, maxWidth - 4);
-      lines.push(
-        prefix + bullet + (isSelected ? chalk4.bold(label) : label)
-      );
+      const styledLabel = isSelected ? chalk4.bold(label) : isCurrent ? chalk4.cyan(label) : label;
+      lines.push(prefix + bullet + styledLabel);
       selectableIdx++;
     }
   }
@@ -3320,9 +3328,9 @@ async function showSelect(opts) {
   const w = modalWidth();
   const maxItems = selectableCount(opts.items);
   if (maxItems === 0) return null;
-  let selectedIndex = 0;
+  let selectedIndex = opts.initialIndex ?? 0;
   const render = () => {
-    const content = buildSelectContent(opts.items, selectedIndex, w - 6);
+    const content = buildSelectContent(opts.items, selectedIndex, w - 6, opts.currentIndex);
     const footer = "\u2191\u2193 Navigate  Enter Select  Esc Cancel";
     const lines = buildModalFrame(opts.title, content, footer, w);
     renderOverlay(opts.dashboardLines, lines, w);
@@ -3725,6 +3733,8 @@ async function handleList(dashboardLines) {
     const currentBranch = await getCurrentBranch();
     const defaultBranch = await getDefaultBranch();
     const items = [];
+    let initialIndex = 0;
+    let selectableIdx = 0;
     const isMain = currentBranch === defaultBranch;
     const mainLabel = defaultBranch + (isMain ? " (current)" : "");
     if (dirty && !isMain) {
@@ -3735,42 +3745,42 @@ async function handleList(dashboardLines) {
     } else {
       items.push({ name: mainLabel, value: "__main__" });
     }
+    if (isMain) initialIndex = selectableIdx;
+    selectableIdx++;
     const inProgressChoices = choices.filter(
       (c) => c.category === "in-progress"
     );
     const openPrChoices = choices.filter((c) => c.category === "open-pr");
     const readyChoices = choices.filter((c) => c.category === "ready");
-    if (inProgressChoices.length > 0) {
-      items.push({ separator: "\u2500\u2500 In Progress \u2500\u2500" });
-      for (const c of inProgressChoices) {
+    const addChoices = (list) => {
+      for (const c of list) {
+        const isCurrent = c.branch === currentBranch;
         items.push({
           name: `#${c.issueNumber} ${c.title}`,
           value: String(c.issueNumber)
         });
+        if (isCurrent) initialIndex = selectableIdx;
+        selectableIdx++;
       }
+    };
+    if (inProgressChoices.length > 0) {
+      items.push({ separator: "\u2500\u2500 In Progress \u2500\u2500" });
+      addChoices(inProgressChoices);
     }
     if (openPrChoices.length > 0) {
       items.push({ separator: "\u2500\u2500 Open PRs \u2500\u2500" });
-      for (const c of openPrChoices) {
-        items.push({
-          name: `#${c.issueNumber} ${c.title}`,
-          value: String(c.issueNumber)
-        });
-      }
+      addChoices(openPrChoices);
     }
     if (readyChoices.length > 0) {
       items.push({ separator: "\u2500\u2500 Ready \u2500\u2500" });
-      for (const c of readyChoices) {
-        items.push({
-          name: `#${c.issueNumber} ${c.title}`,
-          value: String(c.issueNumber)
-        });
-      }
+      addChoices(readyChoices);
     }
     const selected = await showSelect({
       title: "Switch Ticket",
       items,
-      dashboardLines
+      dashboardLines,
+      initialIndex,
+      currentIndex: initialIndex
     });
     if (!selected) return false;
     if (selected === "__main_disabled__") {
@@ -3877,13 +3887,16 @@ async function tuiCommand() {
     isPlaywrightAvailable: false
   };
   let needsRefresh = true;
+  let isFirstLoad = true;
   while (running) {
     if (needsRefresh) {
       clearScreen();
       renderDashboard(lastState, lastActions, void 0, true, versionCheck);
+      const checkInterval = isFirstLoad ? 0 : VERSION_CHECK_INTERVAL_MS;
+      isFirstLoad = false;
       const [state, versionResult] = await Promise.all([
         aggregateState(),
-        checkForUpdates(VERSION_CHECK_INTERVAL_MS).catch(() => null)
+        checkForUpdates(checkInterval).catch(() => null)
       ]);
       const actions = getAvailableActions(state);
       lastState = state;