jira-pat 1.0.1 → 1.0.2

package/AGENTS.md

@@ -1,118 +1,124 @@
 # AGENTS.md - Jira Dashboard
 
+## Project Overview
+
+A Jira Dashboard CLI tool with Express backend (port 5000) and React frontend (port 5173).
+
 ## 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)
-│   └── jest.config.js    # Jest configuration
-└── 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
+├── package.json              # Root - runs both servers with concurrently
+├── bin/
+│   └── jira.js               # CLI entry point for `jira` command
+├── backend/                   # Express API (CommonJS), port 5000
+│   ├── index.js             # Entry point
+│   ├── routes/              # API route handlers (issues.js, projects.js)
+│   ├── service/             # Jira API integration (jiraService.js)
+│   └── __tests__/           # Jest tests
+└── frontend/                 # React app (ES modules + Vite)
+    └── src/
+        ├── App.jsx          # Main component
+        ├── index.css        # All styles (~2500 lines)
+        ├── services/        # API client (api.js)
+        ├── components/      # React components
+        ├── hooks/           # Custom React hooks
+        └── utils/           # Helper functions
 ```
 
 ## Commands
 
 ### Development
 ```bash
-npm start                  # Run both backend (port 5000) and frontend (port 5173)
-cd frontend && npm run dev # Frontend dev server only
-cd backend && npm start    # Backend server only
-```
-
-### Build & Production
-```bash
+npm start                  # Run both backend and frontend concurrently
 npm run build              # Build frontend for production
-cd frontend && npm run build
-cd frontend && npm run preview  # Preview production build
+cd frontend && npm run dev # Frontend dev server only (port 5173)
+cd backend && npm start    # Backend server only (port 5000)
 ```
 
 ### Testing
 
-**Root (runs both workspaces):**
+**Root (runs both):**
 ```bash
-npm test                   # Run all tests (backend + frontend)
+npm test                   # Run all tests
 ```
 
 **Backend (Jest):**
 ```bash
-cd backend && npm test                           # Run all tests with watch mode
-cd backend && npm test -- --coverage             # With coverage report
-cd backend && npm test -- --testPathPattern=auth # Run specific test file
-cd backend && npm test -- --testNamePattern=user # Run tests matching name
-cd backend && npm test -- --testPathPattern=routes/auth.test.js --watchAll=false # Single file, no watch
+cd backend && npm test                              # Watch mode
+cd backend && npm test -- --coverage                # With coverage
+cd backend && npm test -- --testPathPattern=routes/issues.test.js  # Single file
+cd backend && npm test -- --testNamePattern=create # Tests matching name
+cd backend && npm test -- --watchAll=false          # Single run, no watch
 ```
 
 **Frontend (Vitest):**
 ```bash
-cd frontend && npm test                          # Run all tests with watch mode
-cd frontend && npm run test:run                  # Run all tests once (CI mode)
-cd frontend && npm test -- src/services/api.test.js # Run specific file
-cd frontend && npm test -- --grep "should render"   # Run tests matching pattern
-cd frontend && npm test -- --coverage            # With coverage
-```
-
-## 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
+cd frontend && npm test                              # Watch mode
+cd frontend && npm run test:run                    # Single run (CI mode)
+cd frontend && npm test -- src/services/api.test.js # Single file
+cd frontend && npm test -- --grep "should render"   # Pattern match
+cd frontend && npm test -- --coverage               # With coverage
 ```
 
-Create `/frontend/.env` (optional):
-```
-VITE_API_BASE_URL=http://localhost:5000/api
-```
+---
 
-## Code Style
+## Code Style Guidelines
 
-### General
+### General Principles
 - 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
+- Prefer composition over prop drilling
+- Memoize expensive computations with `useMemo`/`React.memo`
 
+### Import Order (Frontend)
 ```jsx
 import React, { useState, useEffect } from 'react';
 import { Search, X } from 'lucide-react';
 import { getIssues } from './services/api';
+import { formatDate } from './utils/helpers';
 import './index.css';
 ```
 
-### Backend (Node.js - CommonJS)
-- Use `require()` and `module.exports`
+### React Components
+- Use `.jsx` extension for components, `.js` for utilities
+- Default export for components, named exports for utilities
+- Functional components with hooks only (no class components)
+- Destructure props in function signature
+
+```jsx
+// Good
+export default function IssueTable({ issues, onRowClick, loading }) {
+  return <table>...</table>;
+}
+
+// Good - hook pattern
+const [data, setData] = useState(null);
+const isLoading = useMemo(() => expensiveCalculation(data), [data]);
+```
+
+### Backend (Node.js)
+- CommonJS: `require()` and `module.exports`
 - Keep routes thin, services thick
+- Always validate input before processing
+- Return appropriate HTTP status codes
 
 ```javascript
 const express = require('express');
 const router = express.Router();
+
+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 });
+  }
+});
+
 module.exports = router;
 ```
 
@@ -121,23 +127,27 @@ module.exports = router;
 | Type | Convention | Example |
 |------|------------|---------|
 | Components | PascalCase | `IssueDrawer` |
+| Hooks | camelCase `useXxx` | `useIssueDrawer` |
+| State setters | `setXxx` | `setIssues` |
 | Functions | camelCase | `fetchIssues` |
 | Constants | UPPER_SNAKE | `STATUS_CHIPS` |
-| CSS Classes | kebab-case | `.issue-table` |
+| CSS classes | kebab-case | `.issue-table` |
 | Files | kebab-case | `api-client.js` |
-| React state | `useXxx`, `setXxx` | `issues`, `setIssues` |
+| Files (components) | PascalCase | `IssueDrawer.jsx` |
+
+---
 
 ## Common Patterns
 
 ### Debounce (search inputs)
 ```jsx
 useEffect(() => {
-  const timer = setTimeout(() => fetchData(), 500);
+  const timer = setTimeout(() => fetchData(searchQuery), 500);
   return () => clearTimeout(timer);
 }, [searchQuery]);
 ```
 
-### Async with Loading/Error
+### Async with Loading/Error State
 ```jsx
 const [loading, setLoading] = useState(false);
 const [error, setError] = useState(null);
@@ -170,8 +180,8 @@ const addToast = (message, type = 'info') => {
 ```jsx
 useEffect(() => {
   const handleKeyDown = (e) => {
-    if (e.key === '/' && !['INPUT', 'TEXTAREA'].includes(document.activeElement.tagName)) {
-      e.preventDefault();
+    if (e.key === 'Escape' && !['INPUT', 'TEXTAREA'].includes(document.activeElement.tagName)) {
+      onClose();
     }
   };
   window.addEventListener('keydown', handleKeyDown);
@@ -179,67 +189,121 @@ useEffect(() => {
 }, []);
 ```
 
-## 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 (A11y)
 
-## Accessibility
-- Always use `aria-label` on icon-only buttons
-- Use semantic HTML (`<button>`, `<nav>`, `<main>`)
+- Always add `aria-label` to icon-only buttons
+- Use semantic HTML: `<button>`, `<nav>`, `<main>`, `<article>`
+- Add `role="alert"` for error messages
 - Support keyboard navigation (Tab, Enter, Escape, Arrow keys)
+- Add `aria-sort="none/ascending/descending"` to sortable table headers
+- Add `scope="col"` to table headers
+- Wrap pagination in `<nav aria-label="Pagination">`
 
 ```jsx
 <button onClick={handleDelete} aria-label="Delete item">
   <TrashIcon size={16} />
 </button>
+
+<nav aria-label="Pagination">
+  <button aria-label="Previous page">Prev</button>
+</nav>
 ```
 
+---
+
 ## CSS Guidelines
-- Use CSS custom properties (variables) for colors, spacing
+
+- Use CSS custom properties (variables) for all colors, spacing, shadows
 - BEM-inspired naming for component styles
 - Avoid inline styles except for dynamic values
+- Group related styles together
+- Use `rem` for sizing, `px` for borders
 
 ```css
 :root {
   --primary: #0052cc;
+  --primary-light: rgba(0, 82, 204, 0.1);
   --spacing-sm: 8px;
   --spacing-md: 16px;
+  --radius-md: 4px;
+  --transition-fast: 150ms ease;
 }
 
-.button { padding: var(--spacing-sm) var(--spacing-md); }
-.button--loading { opacity: 0.7; }
+.issue-table { /* Block */ }
+.issue-table__row { /* Element */ }
+.issue-table__row--active { /* Modifier */ }
 ```
 
+---
+
+## API Design (Backend)
+
+### Response Format
+- Success: `res.json(data)` or `res.status(201).json(data)`
+- Error: `res.status(code).json({ error: 'message', details: error.message })`
+
+### Validation
+- Always validate input with regex or type checking
+- Sanitize JQL queries to prevent injection
+- Limit mutation operations with rate limiting
+
+---
+
+## Testing Guidelines
+
+### Backend (Jest + Supertest)
+- Test file location: `__tests__/filename.test.js`
+- Mock external services (axios calls)
+- Use descriptive test names: `it('should return 404 when issue not found')`
+
+### Frontend (Vitest + Testing Library)
+- Test file location: `src/__tests__/path/to/file.test.jsx`
+- Test behavior, not implementation
+- Use `screen.getByRole`, `screen.getByText` for queries
+- Mock API calls with `vi.fn()` and `mockResolvedValue`
+
+```jsx
+it('should call onRowClick when row is clicked', async () => {
+  render(<IssueTable issues={mockIssues} onRowClick={mockFn} />);
+  fireEvent.click(screen.getByText('TEST-1'));
+  expect(mockFn).toHaveBeenCalledWith('TEST-1');
+});
+```
+
+---
+
+## Environment Variables
+
+### Backend (`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
+```
+
+### Frontend (`frontend/.env`)
+```
+VITE_API_BASE_URL=http://localhost:5000/api
+```
+
+---
+
 ## 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
+- Jira Cloud API v3 endpoints
+- ADF (Atlassian Document Format) for rich text
 
 ## 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
+- File uploads limited to 10MB (multer configuration)
+- Rate limiting on mutation endpoints
+- Input validation and sanitization on all API endpoints

package/README.md

@@ -2,25 +2,115 @@
 
 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`.
+## 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.
+
+---
+
+## Getting Started
+
+### Prerequisites
+
+- 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))
+
+### Installation & Setup
+
+1.  **Download & Install**:
+    ```bash
+    git clone https://github.com/yourusername/jira-dashboard.git
+    cd jira-dashboard
+    npm install
+    ```
+
+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**.
+
+3.  **Launch the App**:
+    ```bash
+    npm start
+    ```
+    Your browser should automatically open to `http://localhost:5000`.
+
+---
+
+## Using the Dashboard (User Guide)
+
+Once the dashboard is open, here is how you can manage your work:
+
+### 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").
+
+### 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. 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.
+
+---
+
+## Development (Technical)
+
+### Running the Backend (API)
+```bash
+cd backend
+npm start
+```
+The API runs on `http://localhost:5000`.
+
+### Running the Frontend (Vite)
+```bash
+cd frontend
+npm run dev
+```
+The frontend runs on `http://localhost:5173` (proxies `/api` to port 5000).
+
+---
+
+## Testing
+
+### Run All Tests
+```bash
+npm test
+```
+
+### Backend Tests
+```bash
+cd backend
+npm test
+```
+
+### Frontend Tests
+```bash
+cd frontend
+npm test
+```
 
 ---
 
@@ -28,37 +118,21 @@ A fast, lightweight, and modern Jira Dashboard built with React, Vite, and Node.
 
 ```
 jira-dashboard/
-├── package.json          # Root configuration for concurrently running both servers
-├── README.md             # This file
-│
+├── bin/                  # CLI setup and start scripts
 ├── 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
+│   ├── routes/           # API Endpoints (Issues, Projects)
+│   ├── service/          # Jira API integration logic
+│   └── __tests__/        # Backend test suite
 │
 └── 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
+    ├── src/
+    │   ├── components/   # React components (Table, Drawer, Modals)
+    │   ├── hooks/        # Custom React hooks (Data fetching, UI state)
+    │   └── __tests__/    # Frontend test suite
 ```
 
 ---
 
-## How To Run
+## License
 
-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`.
+ISC