jira-pat 1.0.3 → 1.0.5

package/README.md

@@ -1,135 +1,155 @@
 # Jira Dashboard
 
-A fast, lightweight, and modern Jira Dashboard built with React, Vite, and Node.js. It avoids CORS and proxy issues by connecting directly to the Jira Cloud API using Basic Authentication within a dedicated Express backend.
-
-## Features
-
-1.  **Direct Jira Cloud Integration**: Connects to the Jira REST API securely via an Express backend.
-2.  **CLI Configuration**: Easy setup with the built-in `jira` CLI tool.
-3.  **Dynamic Filtering**: Filter by project, status, or keyword.
-4.  **Interactive Issue View**: 
-    - Full issue details in a side drawer or standalone page.
-    - Rich text rendering (Markdown/ADF to HTML).
-    - Proxying of Jira-hosted images and attachments.
-    - Status transitions and user assignment.
-    - File uploads directly to Jira tickets.
-5.  **Subtasks & Linked Issues**: Visualize and navigate between related tickets.
-6.  **Backend Caching**: 60-second in-memory caching for performance and API rate-limiting compliance.
-7.  **Fully Tested**: Comprehensive unit and integration tests for both frontend and backend.
-8.  **Error Handling**: Robust error boundaries and toast notifications for a smooth experience.
+View and manage your Jira tickets from a simple dashboard — no need to navigate Jira itself.
 
 ---
 
-## Getting Started
-
-### Prerequisites
+## Before You Begin
 
-- Node.js (v18 or higher recommended)
-- An Atlassian account with a Jira Cloud instance
-- A Jira API Token ([Get one here](https://id.atlassian.com/manage-profile/security/api-tokens))
+You'll need three things set up before you can use the dashboard. This only takes about 5 minutes.
 
-### Installation & Setup
+### 1. Node.js (a behind-the-scenes engine)
 
-1.  **Download & Install**:
-    ```bash
-    git clone https://github.com/yourusername/jira-dashboard.git
-    cd jira-dashboard
-    npm install
-    ```
+The dashboard needs Node.js installed on your computer to run. You don't need to know what it does — just think of it as a required engine.
 
-2.  **Configure your Account**:
-    Run the setup tool to connect your Jira account:
-    ```bash
-    npm link # Optional: allows you to just type 'jira'
-    jira config
-    ```
-    Follow the prompts to enter your **Jira URL**, **Email**, and **API Token**.
+**Check if you already have it:**
+1. Open **Terminal** (Mac) or **Command Prompt** (Windows)
+   - Mac: Press `Cmd + Space`, type *Terminal*, hit Enter
+   - Windows: Press `Win + R`, type *cmd*, hit Enter
+2. Type `node --version` and press Enter
+3. If you see something like `v18.0.0` or higher, you're all set ✅
 
-3.  **Launch the App**:
-    ```bash
-    npm start
-    ```
-    Your browser should automatically open to `http://localhost:5000`.
+**If you don't have it:**
+1. Go to [nodejs.org](https://nodejs.org)
+2. Click the big **"LTS"** download button (LTS = most stable version)
+3. Install it like any other program
+4. Close and reopen your Terminal window before continuing
 
 ---
 
-## Using the Dashboard (User Guide)
+### 2. A Jira API Token (your secure password for the app)
 
-Once the dashboard is open, here is how you can manage your work:
+Instead of using your Jira password directly, you'll create a special token just for this app. It's safer and easy to remove if needed.
 
-### 1. Finding Your Work
-*   **Default View**: When you log in, you will see all issues currently assigned to you.
-*   **Search**: Use the search bar at the top to find specific tickets by typing their title or description. (Tip: Press `/` to jump to search).
-*   **Filters**: Use the **Project** and **Status** dropdowns to narrow down your list (e.g., only show "In Progress" tasks for project "ABC").
+**How to create one:**
+1. Go to [Atlassian API Token page](https://id.atlassian.com/manage-profile/security/api-tokens)
+2. Click **"Create API token"**
+3. Give it any name — for example, *Jira Dashboard*
+4. Click **"Create"**, then **copy the token** that appears
+5. Paste it somewhere safe (like a note on your computer) — you'll need it in the next section and **won't be able to see it again**
 
-### 2. Viewing and Updating Issues
-*   **Open Details**: Click on any row in the table. A side panel will slide out with the full description and comments.
-*   **Change Status**: Inside the panel, click the status button (like "To Do") to move the ticket to a new stage (like "Done").
-*   **Reassign**: Click the user's name or avatar to search for and assign the ticket to someone else.
-*   **Add Attachments**: Drag and drop files directly onto the "Upload" area in the side panel to add them to the Jira ticket.
+---
+
+### 3. Your Jira URL
 
-### 3. Creating New Issues
-*   Click the blue **+** button in the top right corner.
-*   Select the **Project** and **Issue Type** (e.g., Task, Bug).
-*   Enter a **Summary** and click **Create**. The ticket is instantly added to your Jira instance.
+This is the web address you normally type to get to Jira at work. It usually looks like one of these:
+- `https://yourcompany.atlassian.net`
+- `https://jira.yourcompany.com`
 
 ---
 
-## Development (Technical)
+## Setup & Launch
 
-### Running the Backend (API)
-```bash
-cd backend
-npm start
-```
-The API runs on `http://localhost:5000`.
+### Step 1 — Run the one-time setup
 
-### Running the Frontend (Vite)
+Open Terminal (or Command Prompt) and paste this, then press Enter:
 ```bash
-cd frontend
-npm run dev
+npx jira-pat config
 ```
-The frontend runs on `http://localhost:5173` (proxies `/api` to port 5000).
+
+It will ask you for three things:
+- **Jira URL** — the address from Step 3 above
+- **Email** — the email you use to log into Jira
+- **API Token** — the token you created in Step 2
+
+> 🔒 Your details are saved only on your computer and are never sent anywhere else.
+
+**Where your details are saved (for your reference):**
+- Mac/Linux: `~/.jira-dashboard-config.json`
+- Windows: `C:\Users\YourName\.jira-dashboard-config.json`
 
 ---
 
-## Testing
+### Step 2 — Start the dashboard
 
-### Run All Tests
+Each time you want to use the dashboard, run:
 ```bash
-npm test
+npx jira-pat
 ```
 
-### Backend Tests
-```bash
-cd backend
-npm test
+Your browser should open automatically. If it doesn't, open your browser and go to:
 ```
-
-### Frontend Tests
-```bash
-cd frontend
-npm test
+http://localhost:5173
 ```
 
 ---
 
-## Project Structure
+## Using the Dashboard
 
-```
-jira-dashboard/
-├── bin/                  # CLI setup and start scripts
-├── backend/              # Node.js + Express API Layer
-│   ├── routes/           # API Endpoints (Issues, Projects)
-│   ├── service/          # Jira API integration logic
-│   └── __tests__/        # Backend test suite
-│
-└── frontend/             # React + Vite UI
-    ├── src/
-    │   ├── components/   # React components (Table, Drawer, Modals)
-    │   ├── hooks/        # Custom React hooks (Data fetching, UI state)
-    │   └── __tests__/    # Frontend test suite
-```
+### Finding your tickets
+
+- When you open the dashboard, you'll see all tickets currently assigned to you.
+- Use the **search bar** at the top to look up a ticket by keyword. Tip: press `/` on your keyboard to jump straight to it.
+- Use the **Project** and **Status** dropdowns to filter the list down to what you need.
+
+### Viewing and updating a ticket
+
+- **Click any row** to open a side panel with the full details.
+- **Change the status** by clicking the status label (e.g. *In Progress*, *Done*).
+- **Reassign** a ticket by clicking the assignee's name and searching for someone else.
+- **Attach a file** by dragging and dropping it onto the side panel.
+
+### Creating a new ticket
+
+1. Click the blue **+** button in the top-right corner.
+2. Choose a **Project** and **Issue Type** (Task, Bug, Story, etc.).
+3. Write a short **Summary** and click **Create**.
+
+---
+
+## Something Not Working?
+
+| What you're seeing | What to try |
+|--------------------|-------------|
+| *"command not found"* | Node.js isn't installed — go back to Step 1 |
+| *"Cannot connect to Jira"* | Check your Jira URL, email, and API token — run `npx jira-pat config` again |
+| *"Port already in use"* | Close other apps or browser tabs that might be using ports 5000 or 5173 |
+| Browser doesn't open | Manually go to `http://localhost:5173` in your browser |
+
+---
+
+## Features
+
+### Dashboard & Search
+- View all Jira tickets assigned to you
+- Search tickets by keyword, issue key, or summary
+- Filter by project and status
+- Keyboard shortcut `/` to quickly access search
+
+### Issue Management
+- View full issue details in a side panel
+- Update issue status (transitions)
+- Reassign issues to other users
+- Add and remove labels
+- Update fix versions
+- Upload attachments (drag & drop)
+- **Edit issue summary** — click the pencil icon next to the title
+- **Edit issue description** — click the pencil icon next to the description header
+
+### Project Management
+- Create new issues (Task, Bug, Story, Epic, etc.)
+- View available projects
+- Browse project versions/releases
+
+### Comments
+- View and add comments on issues
+- Edit your own comments
+- **@mention team members** — type `@` in the comment box to search and mention project members
+
+### Real-time Updates
+- Optimistic UI updates for faster feedback
+- Loading states and error handling
+- Toast notifications for actions
 
 ---
 

package/backend/__tests__/projects.test.js

@@ -265,5 +265,133 @@ describe('projects routes', () => {
             expect(response.body).toHaveProperty('details');
         });
     });
+
+    describe('GET /api/projects/:projectKey/members', () => {
+        it('should fetch project members', async () => {
+            const mockMembers = [
+                { 
+                    accountId: 'acc1', 
+                    displayName: 'John Doe', 
+                    emailAddress: 'john@example.com',
+                    avatarUrls: { '48x48': 'http://example.com/avatar1.png' }
+                },
+                { 
+                    accountId: 'acc2', 
+                    displayName: 'Jane Smith', 
+                    emailAddress: 'jane@example.com',
+                    avatarUrls: {}
+                }
+            ];
+            jiraService.getProjectMembers.mockResolvedValue(mockMembers);
+
+            const response = await request(server)
+                .get('/api/projects/ADW/members');
+
+            expect(response.status).toBe(200);
+            expect(response.body).toEqual(mockMembers);
+            expect(jiraService.getProjectMembers).toHaveBeenCalledWith('ADW', undefined);
+        });
+
+        it('should pass query parameter when searching', async () => {
+            const mockMembers = [
+                { accountId: 'acc1', displayName: 'John Doe', emailAddress: 'john@example.com', avatarUrls: {} }
+            ];
+            jiraService.getProjectMembers.mockResolvedValue(mockMembers);
+
+            const response = await request(server)
+                .get('/api/projects/ADW/members?query=john');
+
+            expect(response.status).toBe(200);
+            expect(jiraService.getProjectMembers).toHaveBeenCalledWith('ADW', 'john');
+        });
+
+        it('should return empty array when no members', async () => {
+            jiraService.getProjectMembers.mockResolvedValue([]);
+
+            const response = await request(server)
+                .get('/api/projects/EMPTY/members');
+
+            expect(response.status).toBe(200);
+            expect(response.body).toEqual([]);
+        });
+
+        it('should handle Jira API errors', async () => {
+            jiraService.getProjectMembers.mockRejectedValue(
+                new Error('Permission denied')
+            );
+
+            const response = await request(server)
+                .get('/api/projects/ADW/members');
+
+            expect(response.status).toBe(500);
+            expect(response.body.error).toBe('Failed to fetch project members');
+            expect(response.body.details).toContain('Permission denied');
+        });
+
+        it('should handle authentication errors', async () => {
+            jiraService.getProjectMembers.mockRejectedValue(
+                new Error('Jira API Error: 401 - Unauthorized')
+            );
+
+            const response = await request(server)
+                .get('/api/projects/ADW/members');
+
+            expect(response.status).toBe(500);
+            expect(response.body.error).toBe('Failed to fetch project members');
+        });
+
+        it('should handle network errors', async () => {
+            jiraService.getProjectMembers.mockRejectedValue(
+                new Error('connect ECONNREFUSED')
+            );
+
+            const response = await request(server)
+                .get('/api/projects/ADW/members');
+
+            expect(response.status).toBe(500);
+            expect(response.body.details).toContain('ECONNREFUSED');
+        });
+
+        it('should return members with all properties', async () => {
+            const mockMembers = [
+                {
+                    accountId: 'acc123',
+                    displayName: 'Test User',
+                    emailAddress: 'test@company.com',
+                    avatarUrls: {
+                        '48x48': 'http://example.com/avatar.png',
+                        '32x32': 'http://example.com/avatar32.png'
+                    }
+                }
+            ];
+            jiraService.getProjectMembers.mockResolvedValue(mockMembers);
+
+            const response = await request(server)
+                .get('/api/projects/TEST/members');
+
+            expect(response.body[0]).toHaveProperty('accountId', 'acc123');
+            expect(response.body[0]).toHaveProperty('displayName', 'Test User');
+            expect(response.body[0]).toHaveProperty('emailAddress', 'test@company.com');
+            expect(response.body[0]).toHaveProperty('avatarUrls');
+        });
+
+        it('should pass project key to service', async () => {
+            jiraService.getProjectMembers.mockResolvedValue([]);
+
+            await request(server).get('/api/projects/PROJ123/members');
+
+            expect(jiraService.getProjectMembers).toHaveBeenCalledWith('PROJ123', undefined);
+        });
+
+        it('should handle empty query string', async () => {
+            jiraService.getProjectMembers.mockResolvedValue([]);
+
+            const response = await request(server)
+                .get('/api/projects/ADW/members?query=');
+
+            expect(response.status).toBe(200);
+            expect(jiraService.getProjectMembers).toHaveBeenCalledWith('ADW', '');
+        });
+    });
 });
 

package/backend/index.js

@@ -46,18 +46,28 @@ app.get('/api/health', (req, res) => {
 });
 
 // Serve frontend static files
-const frontendDist = path.join(__dirname, '../frontend/dist');
+const frontendDist = path.resolve(__dirname, '..', 'frontend', 'dist');
+console.log('--- Static Assets Setup ---');
+console.log('Searching for frontend at:', frontendDist);
+
 if (require('fs').existsSync(frontendDist)) {
-    console.log('Serving frontend from:', frontendDist);
+    console.log('✅ Frontend dist found. Serving static files.');
     app.use(express.static(frontendDist));
     
-    // Catch-all for SPA: If no other route matches (and it's not an API call), serve index.html
     app.use((req, res, next) => {
         if (!req.path.startsWith('/api') && req.method === 'GET') {
-            return res.sendFile(path.join(frontendDist, 'index.html'));
+            const indexPath = path.resolve(frontendDist, 'index.html');
+            if (require('fs').existsSync(indexPath)) {
+                return res.sendFile(indexPath);
+            } else {
+                console.error('❌ Error: index.html not found even though dist exists!');
+                return res.status(404).send('Dashboard files missing (index.html)');
+            }
         }
         next();
     });
+} else {
+    console.warn('⚠️ Warning: frontend/dist directory NOT found at ' + frontendDist);
 }
 
 app.listen(PORT, () => {

package/backend/routes/issues.js

@@ -270,4 +270,38 @@ router.put('/:issueKey', mutationLimiter, async (req, res) => {
     }
 });
 
+// PUT /api/issues/:issueKey/summary
+router.put('/:issueKey/summary', mutationLimiter, async (req, res) => {
+    const error = validateIssueKey(req.params.issueKey);
+    if (error) return res.status(400).json({ error });
+    
+    try {
+        const { summary } = req.body;
+        if (!summary || typeof summary !== 'string') {
+            return res.status(400).json({ error: 'Summary is required' });
+        }
+        if (summary.length > 255) {
+            return res.status(400).json({ error: 'Summary must be under 255 characters' });
+        }
+        await jiraService.updateIssueSummary(req.params.issueKey, summary.trim());
+        res.json({ success: true });
+    } catch (error) {
+        res.status(500).json({ error: 'Failed to update summary', details: error.message });
+    }
+});
+
+// PUT /api/issues/:issueKey/description
+router.put('/:issueKey/description', mutationLimiter, async (req, res) => {
+    const error = validateIssueKey(req.params.issueKey);
+    if (error) return res.status(400).json({ error });
+    
+    try {
+        const { description } = req.body;
+        await jiraService.updateIssueDescription(req.params.issueKey, description || '');
+        res.json({ success: true });
+    } catch (error) {
+        res.status(500).json({ error: 'Failed to update description', details: error.message });
+    }
+});
+
 module.exports = router;

package/backend/routes/projects.js

@@ -32,4 +32,15 @@ router.get('/:projectKey/versions', async (req, res) => {
     }
 });
 
+// GET /api/projects/:projectKey/members
+router.get('/:projectKey/members', async (req, res) => {
+    try {
+        const { query } = req.query;
+        const members = await jiraService.getProjectMembers(req.params.projectKey, query);
+        res.json(members);
+    } catch (error) {
+        res.status(500).json({ error: 'Failed to fetch project members', details: error.message });
+    }
+});
+
 module.exports = router;