jira-pat 1.0.0

package/AGENTS.md

@@ -0,0 +1,218 @@
+# AGENTS.md - Jira Dashboard
+
+## Project Structure
+
+```
+jira-dashboard/
+├── package.json          # Root - runs both servers with concurrently
+├── backend/              # Express API (CommonJS), port 5000
+│   ├── index.js          # Entry point
+│   ├── routes/           # API route handlers
+│   └── service/          # Jira API integration (axios + node-cache)
+└── frontend/             # React app (ES modules + Vite), port 5173
+    ├── src/
+    │   ├── App.jsx           # Main component (~400 lines)
+    │   ├── index.css         # All styles (~1700 lines)
+    │   ├── services/         # API client (axios)
+    │   ├── components/       # React components
+    │   │   ├── IssueDrawer.jsx
+    │   │   ├── CreateIssueModal.jsx
+    │   │   ├── IssueTable.jsx
+    │   │   ├── StandaloneIssuePage.jsx
+    │   │   └── ToastContainer.jsx
+    │   └── hooks/            # Custom React hooks
+    │       ├── useIssueDrawer.js
+    │       ├── useToasts.js
+    │       └── useIssuesList.js
+    └── vite.config.js
+```
+
+## Commands
+
+```bash
+# Root - runs both servers
+npm start
+
+# Frontend
+cd frontend && npm run dev        # Dev server (port 5173)
+cd frontend && npm run build      # Production build
+cd frontend && npm run preview    # Preview build
+
+# Backend
+cd backend && npm start           # Start server (port 5000)
+```
+
+## Environment Setup
+
+Create `/backend/.env`:
+```
+JIRA_BASE_URL=https://your-domain.atlassian.net
+JIRA_EMAIL=your-email@example.com
+JIRA_PAT=your-api-token
+PORT=5000
+BACKEND_BASE_URL=http://localhost:5000
+```
+
+Create `/frontend/.env` (optional):
+```
+VITE_API_BASE_URL=http://localhost:5000/api
+```
+
+## Code Style
+
+### General
+- No comments unless explaining non-obvious logic
+- Small, focused functions (single responsibility)
+- Prefer early returns to reduce nesting
+- 4-space indentation (backend), standard formatting (frontend)
+
+### Frontend (React + Vite - ES Modules)
+- `.jsx` for React components, `.js` for utilities
+- Named exports for utilities, default export for components
+- Functional components with hooks only (no class components)
+- Import order: React → external libs → internal modules → CSS
+
+```jsx
+import React, { useState, useEffect } from 'react';
+import { Search, X } from 'lucide-react';
+import { getIssues } from './services/api';
+import './index.css';
+```
+
+### Backend (Node.js - CommonJS)
+- Use `require()` and `module.exports`
+- Keep routes thin, services thick
+
+```javascript
+const express = require('express');
+const router = express.Router();
+module.exports = router;
+```
+
+### Naming Conventions
+
+| Type | Convention | Example |
+|------|------------|---------|
+| Components | PascalCase | `IssueDrawer` |
+| Functions | camelCase | `fetchIssues` |
+| Constants | UPPER_SNAKE | `STATUS_CHIPS` |
+| CSS Classes | kebab-case | `.issue-table` |
+| Files | kebab-case | `api-client.js` |
+| React state | `useXxx`, `setXxx` | `issues`, `setIssues` |
+
+## Common Patterns
+
+### Debounce (search inputs)
+```jsx
+useEffect(() => {
+  const timer = setTimeout(() => fetchData(), 500);
+  return () => clearTimeout(timer);
+}, [searchQuery]);
+```
+
+### Async with Loading/Error
+```jsx
+const [loading, setLoading] = useState(false);
+const [error, setError] = useState(null);
+
+const fetchData = async () => {
+  setLoading(true);
+  setError(null);
+  try {
+    const data = await apiCall();
+    setData(data);
+  } catch (err) {
+    setError(err.message || 'Something went wrong');
+  } finally {
+    setLoading(false);
+  }
+};
+```
+
+### Toast Notifications
+```jsx
+const [toasts, setToasts] = useState([]);
+const addToast = (message, type = 'info') => {
+  const id = Date.now();
+  setToasts(prev => [...prev, { id, message, type }]);
+  setTimeout(() => setToasts(prev => prev.filter(t => t.id !== id)), 4000);
+};
+```
+
+### Keyboard Shortcuts
+```jsx
+useEffect(() => {
+  const handleKeyDown = (e) => {
+    if (e.key === '/' && !['INPUT', 'TEXTAREA'].includes(document.activeElement.tagName)) {
+      e.preventDefault();
+    }
+  };
+  window.addEventListener('keydown', handleKeyDown);
+  return () => window.removeEventListener('keydown', handleKeyDown);
+}, []);
+```
+
+## Error Handling
+
+### Backend API Routes
+```javascript
+router.get('/:id', async (req, res) => {
+  try {
+    const data = await service.getData(req.params.id);
+    if (!data) return res.status(404).json({ error: 'Not found' });
+    res.json(data);
+  } catch (error) {
+    console.error('Error:', error.message);
+    res.status(500).json({ error: 'Server error', details: error.message });
+  }
+});
+```
+
+### Frontend
+```jsx
+{error && (
+  <div className="error" role="alert">
+    <AlertCircle size={16} />
+    {error}
+  </div>
+)}
+```
+
+## Accessibility
+- Always use `aria-label` on icon-only buttons
+- Use semantic HTML (`<button>`, `<nav>`, `<main>`)
+- Support keyboard navigation (Tab, Enter, Escape, Arrow keys)
+
+```jsx
+<button onClick={handleDelete} aria-label="Delete item">
+  <TrashIcon size={16} />
+</button>
+```
+
+## CSS Guidelines
+- Use CSS custom properties (variables) for colors, spacing
+- BEM-inspired naming for component styles
+- Avoid inline styles except for dynamic values
+
+```css
+:root {
+  --primary: #0052cc;
+  --spacing-sm: 8px;
+  --spacing-md: 16px;
+}
+
+.button { padding: var(--spacing-sm) var(--spacing-md); }
+.button--loading { opacity: 0.7; }
+```
+
+## Jira API Integration
+- Uses axios with 10-second timeout
+- 60-second in-memory cache (node-cache)
+- Basic Auth with Jira PAT for authentication
+- Uses JQL for searching issues
+
+## Security
+- Never commit `.env` files (in `.gitignore`)
+- API credentials use Basic Auth with Jira PAT
+- File uploads limited to 10MB
+- Input validation on all API endpoints

package/README.md

@@ -0,0 +1,64 @@
+# 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 Currently Supported
+
+1. **Direct Jira Cloud Integration**: Uses your Atlassian Email and API Token securely to fetch real-time Jira data.
+2. **"My Assigned Issues" View**: By default, the API automatically fetches tickets currently assigned to you (`currentUser()`).
+3. **Dynamic Filtering**:
+   - Filter by **Project Key** (e.g. `ABC`)
+   - Search by **Summary / Text** content
+   - Filter by **Ticket Status** (To Do, In Progress, Done, Closed)
+4. **Interactive Side Drawer**: Click an issue row to load real-time deep-dive details.
+   - **Rich Media & Comments**: Renders descriptions and comments with inline images seamlessly proxied securely from Jira.
+   - **Subtasks & Linked Issues**: Visual hierarchy mapping of attached Jira issues, enabling clickable exploration.
+   - **Issue Transitions**: Update ticket stages (e.g., "To Do" -> "In Progress") directly within the app.
+   - **Ticket Assignment**: Searchable user dropdown directly mapped to your active Jira user directory.
+   - **File Attachments**: One-click upload functionality for files mapped directly onto tickets.
+5. **Create New Issues**: Global "+" action triggering dynamic Issue schemas directly synced from Jira projects.
+6. **Fast, Modern UI**: Refactored with `lucide-react` icons, toast notifications, and animated skeleton loaders.
+7. **Keyboard Navigation**: Press `/` to focus search, `Enter` to open an issue, and `Esc` to close modals.
+8. **Backend Caching & Proxying**: 60-second in-memory caching via `node-cache` bypassing CORS/Auth blocks.
+9. **Single Command Start**: Run both the React frontend and Node backend simultaneously using `npm start`.
+
+---
+
+## Project Structure
+
+```
+jira-dashboard/
+├── package.json          # Root configuration for concurrently running both servers
+├── README.md             # This file
+│
+├── backend/              # Node.js + Express API Layer
+│   ├── .env              # Secrets (JIRA_BASE_URL, JIRA_EMAIL, JIRA_PAT)
+│   ├── index.js          # Main Express server and configuration
+│   ├── package.json      # Backend dependencies (express, axios, cors)
+│   ├── routes/
+│   │   └── issues.js     # Route logic for /api/issues
+│   └── service/
+│       └── jiraService.js# Jira REST API communication & JQL construction
+│
+└── frontend/             # React + Vite UI
+    ├── package.json      # Frontend dependencies (react, lucide-react)
+    ├── vite.config.js    # Vite configuration
+    ├── index.html        # App entry HTML
+    └── src/
+        ├── main.jsx      # React DOM entry point
+        ├── App.jsx       # Main Dashboard View and Filters
+        ├── index.css     # Clean, modern UI Styling
+        └── services/
+            └── api.js    # Axios client connecting to backend /api/issues
+```
+
+---
+
+## How To Run
+
+1. Open `/backend/.env` and ensure your `JIRA_BASE_URL`, `JIRA_EMAIL`, and `JIRA_PAT` (Atlassian API Token) are filled in.
+2. Run the application from the root directory:
+```bash
+npm start
+```
+3. Open your browser to `http://localhost:5173`.

package/backend/.env.example

@@ -0,0 +1 @@
+BACKEND_BASE_URL=http://localhost:5000

package/backend/__tests__/getJiraClient.test.js

@@ -0,0 +1,57 @@
+jest.mock('dotenv', () => ({ config: jest.fn() }));
+jest.mock('node-cache');
+
+const NodeCache = require('node-cache');
+const mockCacheInstance = {
+    get: jest.fn(),
+    set: jest.fn(),
+    del: jest.fn(),
+    flushAll: jest.fn(),
+    keys: jest.fn(() => [])
+};
+NodeCache.mockImplementation(() => mockCacheInstance);
+
+describe('getJiraClient config validation', () => {
+    beforeEach(() => {
+        jest.resetModules();
+        jest.clearAllMocks();
+    });
+
+    it('should throw when JIRA_BASE_URL and JIRA_PAT are not set', async () => {
+        delete process.env.JIRA_BASE_URL;
+        delete process.env.JIRA_PAT;
+        delete process.env.JIRA_EMAIL;
+        jest.mock('axios');
+        const service = require('../service/jiraService');
+        await expect(service.searchIssues({})).rejects.toThrow(
+            'JIRA_BASE_URL or JIRA_PAT is not configured in .env'
+        );
+        process.env.JIRA_BASE_URL = 'https://test.atlassian.net';
+        process.env.JIRA_PAT = 'test-pat';
+    });
+
+    it('should use Bearer auth when JIRA_EMAIL is not set', async () => {
+        delete process.env.JIRA_EMAIL;
+        process.env.JIRA_BASE_URL = 'https://test.atlassian.net';
+        process.env.JIRA_PAT = 'test-pat';
+        process.env.BACKEND_BASE_URL = 'http://localhost:5000';
+        jest.mock('axios');
+        const axios = require('axios');
+        const mockAxiosInstance = {
+            get: jest.fn().mockResolvedValue({ data: { issues: [], total: 0 } }),
+            post: jest.fn(),
+            put: jest.fn(),
+            defaults: { baseURL: 'https://test.atlassian.net' }
+        };
+        axios.create.mockReturnValue(mockAxiosInstance);
+        const service = require('../service/jiraService');
+        await service.searchIssues({ project: 'TEST' });
+        expect(axios.create).toHaveBeenCalledWith(
+            expect.objectContaining({
+                headers: expect.objectContaining({
+                    Authorization: expect.stringMatching(/^Bearer /)
+                })
+            })
+        );
+    });
+});