jira-ai 1.0.1 → 1.2.0

package/README.md

@@ -191,6 +191,43 @@ When `authType` is set to `service_account`, jira-ai automatically:
 
 Existing configurations using standard API tokens are unaffected.
 
+## Saved Queries
+
+Define reusable JQL queries in your `settings.yaml` under the `saved-queries` key to avoid repeating common searches.
+
+### Configuration
+
+Add a `saved-queries` map to your `settings.yaml` — each key is a query name (lowercase alphanumeric with hyphens) and each value is a JQL string:
+
+```yaml
+saved-queries:
+  my-open-bugs: "project = PROJ AND status = Open AND issuetype = Bug"
+  overdue-tasks: "project = PROJ AND duedate < now() AND status != Done"
+  my-assignee: "assignee = currentUser()"
+```
+
+### Usage
+
+Run a saved query by name:
+
+```bash
+jira-ai issue search --query my-open-bugs
+```
+
+List all configured saved queries:
+
+```bash
+jira-ai issue search --list-queries
+```
+
+Combine with result limits:
+
+```bash
+jira-ai issue search --query overdue-tasks --limit 10
+```
+
+Saved queries are mutually exclusive with raw JQL — you cannot provide both a positional JQL argument and `--query` at the same time.
+
 ## Configuration & Restrictions
 
 Tool allows you to have very complex configutations of what Projects/Jira commands/Issue types you would have acess to thought the tool.

package/dist/cli.js

@@ -20,6 +20,7 @@ import { listLinkTypesCommand } from './commands/list-link-types.js';
 import { createTaskCommand } from './commands/create-task.js';
 import { transitionCommand, listTransitionsCommand } from './commands/transition.js';
 import { issueAssignCommand } from './commands/issue.js';
+import { uploadAttachmentCommand, listAttachmentsCommand, downloadAttachmentCommand, deleteAttachmentCommand, } from './commands/attach.js';
 import { getIssueStatisticsCommand } from './commands/get-issue-statistics.js';
 import { getPersonWorklogCommand } from './commands/get-person-worklog.js';
 import { isCommandAllowed, getAllowedCommands } from './lib/settings.js';
@@ -36,7 +37,7 @@ import { checkForUpdate, formatUpdateMessage, checkForUpdateSync } from './lib/u
 import { CliError } from './types/errors.js';
 import { CommandError } from './lib/errors.js';
 import { initJsonMode, outputError } from './lib/json-mode.js';
-import { CreateTaskSchema, UpdateDescriptionSchema, ProjectFieldsSchema, ConfluenceAddCommentSchema, RunJqlSchema, GetPersonWorklogSchema, GetIssueStatisticsSchema, EpicListSchema, EpicCreateSchema, EpicUpdateSchema, EpicLinkSchema, EpicMaxSchema, validateOptions, IssueKeySchema, ProjectKeySchema, TimeframeSchema, BoardListSchema, BoardIssuesSchema, BoardRankSchema, SprintListSchema, SprintCreateSchema, SprintUpdateSchema, SprintIssuesSchema, SprintMoveSchema, BacklogMoveSchema, } from './lib/validation.js';
+import { CreateTaskSchema, UpdateDescriptionSchema, ProjectFieldsSchema, ConfluenceAddCommentSchema, RunJqlSchema, GetPersonWorklogSchema, GetIssueStatisticsSchema, EpicListSchema, EpicCreateSchema, EpicUpdateSchema, EpicLinkSchema, EpicMaxSchema, validateOptions, IssueKeySchema, ProjectKeySchema, TimeframeSchema, BoardListSchema, BoardIssuesSchema, BoardRankSchema, SprintListSchema, SprintCreateSchema, SprintUpdateSchema, SprintIssuesSchema, SprintMoveSchema, BacklogMoveSchema, AttachUploadSchema, AttachDownloadSchema, } from './lib/validation.js';
 import { realpathSync } from 'fs';
 // Create CLI program
 const program = new Command();
@@ -130,14 +131,20 @@ issue
     .option('--custom-field <field=value>', 'Custom field in fieldId=value format (repeatable)', (val, prev) => [...(prev || []), val], [])
     .action(withPermission('issue.create', createTaskCommand, { schema: CreateTaskSchema }));
 issue
-    .command('search <jql-query>')
-    .description('Execute a JQL search query. Returns issues with key, summary, status, assignee, and priority.')
+    .command('search [jql-query]')
+    .description('Execute a JQL search query. Provide raw JQL or use --query to reference a saved query.')
     .option('-l, --limit <number>', 'Maximum number of results (default: 50)', '50')
+    .option('--query <name>', 'Use a saved query by name (mutually exclusive with positional JQL)')
+    .option('--list-queries', 'List all available saved queries')
     .action(withPermission('issue.search', runJqlCommand, {
     schema: RunJqlSchema,
     validateArgs: (args) => {
-        if (typeof args[0] !== 'string' || args[0].trim() === '') {
-            throw new CliError('JQL query cannot be empty');
+        const jqlQuery = args[0];
+        const opts = args[args.length - 2];
+        const hasQuery = opts && opts.query;
+        const hasListQueries = opts && opts.listQueries;
+        if (!hasQuery && !hasListQueries && (typeof jqlQuery !== 'string' || jqlQuery.trim() === '')) {
+            throw new CliError('JQL query cannot be empty. Provide a JQL query, use --query <name>, or use --list-queries.');
         }
     }
 }));
@@ -281,6 +288,46 @@ issueLink
     .command('types')
     .description('List all available issue link types for the Jira instance.')
     .action(withPermission('issue.link.types', listLinkTypesCommand));
+// Issue attach subcommands
+const issueAttach = issue
+    .command('attach')
+    .description('Manage issue attachments');
+issueAttach
+    .command('upload <issue-key>')
+    .description('Upload one or more files as attachments to a Jira issue.')
+    .requiredOption('--file <path...>', 'File path(s) to upload (repeatable)')
+    .action(withPermission('issue.attach.upload', (issueKey, options) => {
+    return uploadAttachmentCommand(issueKey, options.file);
+}, {
+    schema: AttachUploadSchema,
+    validateArgs: (args) => validateOptions(IssueKeySchema, args[0])
+}));
+issueAttach
+    .command('list <issue-key>')
+    .description('List all attachments for a Jira issue.')
+    .action(withPermission('issue.attach.list', listAttachmentsCommand, {
+    validateArgs: (args) => validateOptions(IssueKeySchema, args[0])
+}));
+issueAttach
+    .command('download <issue-key>')
+    .description('Download an attachment from a Jira issue.')
+    .requiredOption('--id <attachment-id>', 'Attachment ID to download')
+    .option('--output <path>', 'Output file path (defaults to attachment filename in current directory)')
+    .action(withPermission('issue.attach.download', (issueKey, options) => {
+    return downloadAttachmentCommand(issueKey, options.id, options.output);
+}, {
+    schema: AttachDownloadSchema,
+    validateArgs: (args) => validateOptions(IssueKeySchema, args[0])
+}));
+issueAttach
+    .command('delete <issue-key>')
+    .description('Delete an attachment from a Jira issue.')
+    .requiredOption('--id <attachment-id>', 'Attachment ID to delete')
+    .action(withPermission('issue.attach.delete', (issueKey, options) => {
+    return deleteAttachmentCommand(issueKey, options.id);
+}, {
+    validateArgs: (args) => validateOptions(IssueKeySchema, args[0])
+}));
 // =============================================================================
 // PROJECT COMMANDS
 // =============================================================================

package/dist/commands/attach.js

@@ -0,0 +1,112 @@
+import { addIssueAttachment, getIssueAttachments, downloadAttachment, deleteAttachment, validateIssuePermissions, } from '../lib/jira-client.js';
+import { CommandError } from '../lib/errors.js';
+import { validateOptions, IssueKeySchema } from '../lib/validation.js';
+import { outputResult } from '../lib/json-mode.js';
+export async function uploadAttachmentCommand(issueKey, filePaths) {
+    if (!issueKey || issueKey.trim() === '') {
+        throw new CommandError('Issue key is required');
+    }
+    validateOptions(IssueKeySchema, issueKey);
+    if (!filePaths || filePaths.length === 0) {
+        throw new CommandError('At least one file path is required');
+    }
+    await validateIssuePermissions(issueKey, 'issue.attach.upload');
+    try {
+        const attachments = await addIssueAttachment(issueKey, filePaths);
+        outputResult({ success: true, issueKey, attachments });
+    }
+    catch (error) {
+        if (error instanceof CommandError)
+            throw error;
+        const errorMsg = error.message?.toLowerCase() || '';
+        const hints = [];
+        if (errorMsg.includes('404')) {
+            hints.push('Check that the issue key is correct');
+        }
+        else if (errorMsg.includes('403')) {
+            hints.push('You may not have permission to attach files to this issue');
+        }
+        else if (errorMsg.includes('enoent') || errorMsg.includes('no such file')) {
+            hints.push('Check that the file path is correct and the file exists');
+        }
+        throw new CommandError(`Failed to upload attachment: ${error.message}`, { hints });
+    }
+}
+export async function listAttachmentsCommand(issueKey) {
+    if (!issueKey || issueKey.trim() === '') {
+        throw new CommandError('Issue key is required');
+    }
+    validateOptions(IssueKeySchema, issueKey);
+    await validateIssuePermissions(issueKey, 'issue.attach.list');
+    try {
+        const attachments = await getIssueAttachments(issueKey);
+        outputResult(attachments);
+    }
+    catch (error) {
+        if (error instanceof CommandError)
+            throw error;
+        const errorMsg = error.message?.toLowerCase() || '';
+        const hints = [];
+        if (errorMsg.includes('404')) {
+            hints.push('Check that the issue key is correct');
+        }
+        else if (errorMsg.includes('403')) {
+            hints.push('You may not have permission to view attachments for this issue');
+        }
+        throw new CommandError(`Failed to list attachments: ${error.message}`, { hints });
+    }
+}
+export async function downloadAttachmentCommand(issueKey, attachmentId, outputPath) {
+    if (!issueKey || issueKey.trim() === '') {
+        throw new CommandError('Issue key is required');
+    }
+    validateOptions(IssueKeySchema, issueKey);
+    if (!attachmentId || attachmentId.trim() === '') {
+        throw new CommandError('Attachment ID is required');
+    }
+    await validateIssuePermissions(issueKey, 'issue.attach.download');
+    try {
+        const savedPath = await downloadAttachment(issueKey, attachmentId, outputPath);
+        outputResult({ success: true, attachmentId, outputPath: savedPath });
+    }
+    catch (error) {
+        if (error instanceof CommandError)
+            throw error;
+        const errorMsg = error.message?.toLowerCase() || '';
+        const hints = [];
+        if (errorMsg.includes('404')) {
+            hints.push('Check that the attachment ID is correct');
+        }
+        else if (errorMsg.includes('403')) {
+            hints.push('You may not have permission to download this attachment');
+        }
+        throw new CommandError(`Failed to download attachment: ${error.message}`, { hints });
+    }
+}
+export async function deleteAttachmentCommand(issueKey, attachmentId) {
+    if (!issueKey || issueKey.trim() === '') {
+        throw new CommandError('Issue key is required');
+    }
+    validateOptions(IssueKeySchema, issueKey);
+    if (!attachmentId || attachmentId.trim() === '') {
+        throw new CommandError('Attachment ID is required');
+    }
+    await validateIssuePermissions(issueKey, 'issue.attach.delete');
+    try {
+        await deleteAttachment(issueKey, attachmentId);
+        outputResult({ success: true, issueKey, attachmentId });
+    }
+    catch (error) {
+        if (error instanceof CommandError)
+            throw error;
+        const errorMsg = error.message?.toLowerCase() || '';
+        const hints = [];
+        if (errorMsg.includes('404')) {
+            hints.push('Check that the attachment ID is correct');
+        }
+        else if (errorMsg.includes('403')) {
+            hints.push('You may not have permission to delete this attachment');
+        }
+        throw new CommandError(`Failed to delete attachment: ${error.message}`, { hints });
+    }
+}

package/dist/commands/run-jql.js

@@ -1,11 +1,35 @@
 import { searchIssuesByJql } from '../lib/jira-client.js';
 import { outputResult } from '../lib/json-mode.js';
+import { getSavedQuery, listSavedQueries } from '../lib/settings.js';
+import { CliError } from '../types/errors.js';
 export async function runJqlCommand(jqlQuery, options) {
-    // Parse and validate limit parameter
+    // Handle --list-queries
+    if (options.listQueries) {
+        const queries = listSavedQueries();
+        outputResult({ queries });
+        return;
+    }
+    // Mutual exclusion: can't have both positional JQL and --query
+    if (jqlQuery && jqlQuery.trim() !== '' && options.query) {
+        throw new CliError('Cannot specify both JQL query and --query. Use one or the other.');
+    }
+    let resolvedJql;
+    if (options.query) {
+        const savedJql = getSavedQuery(options.query);
+        if (savedJql === undefined) {
+            const available = listSavedQueries().map((q) => q.name).join(', ');
+            const availableMsg = available ? available : '(none)';
+            throw new CliError(`Saved query '${options.query}' not found. Available: ${availableMsg}`);
+        }
+        resolvedJql = savedJql;
+    }
+    else {
+        resolvedJql = jqlQuery;
+    }
     let maxResults = options.limit || 50;
     if (maxResults > 1000) {
         maxResults = 1000;
     }
-    const issues = await searchIssuesByJql(jqlQuery, maxResults);
+    const issues = await searchIssuesByJql(resolvedJql, maxResults);
     outputResult(issues);
 }

package/dist/lib/jira-client.js

@@ -110,6 +110,7 @@ export async function getTaskWithDetails(taskId, options = {}) {
             'issuetype',
             'priority',
             'resolution',
+            'attachment',
         ],
     });
     // Extract comments
@@ -175,11 +176,15 @@ export async function getTaskWithDetails(taskId, options = {}) {
     // Extract watchers
     const watchers = [];
     if (issue.fields.watches?.isWatching) {
-        // If we only need to know if the current user is watching, isWatching is enough.
-        // But the requirement might mean "any of these roles".
-        // For now, if isWatching is true, we add current user's accountId (placeholder)
-        // Actually, we can fetch watchers detail if needed, but Jira's getIssue returns watches info for current user.
     }
+    // Extract attachments
+    const attachments = (issue.fields.attachment || []).map((att) => ({
+        id: att.id,
+        filename: att.filename,
+        size: att.size,
+        author: att.author?.displayName || 'Unknown',
+        created: att.created,
+    }));
     return {
         id: issue.id || '',
         key: issue.key || '',
@@ -208,7 +213,8 @@ export async function getTaskWithDetails(taskId, options = {}) {
         parent,
         subtasks,
         history,
-        watchers: issue.fields.watches?.isWatching ? ['CURRENT_USER'] : [], // Simple flag for now
+        watchers: issue.fields.watches?.isWatching ? ['CURRENT_USER'] : [],
+        attachments,
     };
 }
 /**
@@ -951,3 +957,84 @@ export async function getAvailableLinkTypes() {
     }));
 }
 export const getEpics = listEpics;
+/**
+ * Upload one or more files as attachments to a Jira issue
+ */
+export async function addIssueAttachment(issueKey, filePaths) {
+    const client = getJiraClient();
+    const fs = await import('fs');
+    const path = await import('path');
+    const attachments = filePaths.map((filePath) => ({
+        filename: path.basename(filePath),
+        file: fs.readFileSync(filePath),
+    }));
+    const result = await client.issueAttachments.addAttachment({
+        issueIdOrKey: issueKey,
+        attachment: attachments,
+    });
+    const items = Array.isArray(result) ? result : [result];
+    return items.map((att) => ({
+        id: att.id || '',
+        filename: att.filename || '',
+        mimeType: att.mimeType || '',
+        size: att.size || 0,
+        created: att.created || '',
+        author: {
+            displayName: att.author?.displayName || '',
+            emailAddress: att.author?.emailAddress,
+        },
+        content: att.content || '',
+    }));
+}
+/**
+ * List all attachments for a Jira issue
+ */
+export async function getIssueAttachments(issueKey) {
+    const client = getJiraClient();
+    const issue = await client.issues.getIssue({
+        issueIdOrKey: issueKey,
+        fields: ['attachment'],
+    });
+    const attachments = issue.fields?.attachment || [];
+    return attachments.map((att) => ({
+        id: att.id || '',
+        filename: att.filename || '',
+        mimeType: att.mimeType || '',
+        size: att.size || 0,
+        created: att.created || '',
+        author: {
+            displayName: att.author?.displayName || '',
+            emailAddress: att.author?.emailAddress,
+        },
+        content: att.content || '',
+    }));
+}
+/**
+ * Download an attachment by ID, saving to outputPath (or current dir if not specified)
+ * Returns the path where the file was saved
+ */
+export async function downloadAttachment(issueKey, attachmentId, outputPath) {
+    const client = getJiraClient();
+    const fs = await import('fs');
+    const path = await import('path');
+    // Get attachment metadata to find the filename
+    const issue = await client.issues.getIssue({
+        issueIdOrKey: issueKey,
+        fields: ['attachment'],
+    });
+    const attachments = issue.fields?.attachment || [];
+    const meta = attachments.find((a) => a.id === attachmentId);
+    const rawFilename = meta?.filename || attachmentId;
+    const safeFilename = path.basename(rawFilename).replace(/\.\./g, '');
+    const destPath = outputPath || path.join(process.cwd(), safeFilename);
+    const content = await client.issueAttachments.getAttachmentContent(attachmentId);
+    fs.writeFileSync(destPath, Buffer.from(content));
+    return destPath;
+}
+/**
+ * Delete an attachment by ID
+ */
+export async function deleteAttachment(issueKey, attachmentId) {
+    const client = getJiraClient();
+    await client.issueAttachments.removeAttachment(attachmentId);
+}

package/dist/lib/settings.js

@@ -4,6 +4,16 @@ import os from 'os';
 import yaml from 'js-yaml';
 import { CliError } from '../types/errors.js';
 import { SettingsSchema } from './validation.js';
+export function getSavedQuery(name) {
+    const settings = loadSettings();
+    return settings.savedQueries?.[name];
+}
+export function listSavedQueries() {
+    const settings = loadSettings();
+    if (!settings.savedQueries)
+        return [];
+    return Object.entries(settings.savedQueries).map(([name, jql]) => ({ name, jql }));
+}
 // Mapping from old flat command names to new hierarchical paths
 export const LEGACY_COMMAND_MAP = {
     'me': 'user.me',

package/dist/lib/validation.js

@@ -113,6 +113,8 @@ export const UpdateDescriptionSchema = z.object({
 });
 export const RunJqlSchema = z.object({
     limit: NumericStringSchema.optional(),
+    query: z.string().optional(),
+    listQueries: z.boolean().optional(),
 });
 export const TimeframeSchema = z.string().regex(/^\d+d$/, 'Timeframe must be in format like "7d" or "30d"');
 export const GetPersonWorklogSchema = z.object({
@@ -157,10 +159,12 @@ export const OrganizationSettingsSchema = z.object({
     'allowed-commands': z.array(z.string()).nullish().transform(val => val || DEFAULT_ALLOWED_COMMANDS),
     'allowed-confluence-spaces': z.array(z.string()).nullish().transform(val => val || ['all']),
 });
+export const SavedQueryNameSchema = z.string().regex(/^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$/, 'Query name must be lowercase alphanumeric with hyphens (e.g., "my-query"), cannot start or end with a hyphen');
 export const SettingsSchema = z.object({
     defaults: OrganizationSettingsSchema.optional(),
     projects: z.array(ProjectSettingSchema).optional(),
     commands: z.array(z.string()).optional(),
+    savedQueries: z.record(SavedQueryNameSchema, z.string().min(1)).optional(),
 });
 // =============================================================================
 // EPIC VALIDATION SCHEMAS
@@ -240,3 +244,13 @@ export const SprintMoveSchema = z.object({
 export const BacklogMoveSchema = z.object({
     issues: z.array(z.string().trim().min(1)).min(1, 'At least one issue key is required'),
 });
+// =============================================================================
+// ATTACHMENT VALIDATION SCHEMAS
+// =============================================================================
+export const AttachUploadSchema = z.object({
+    file: z.array(z.string().trim().min(1, 'File path is required')).min(1, 'At least one file path is required'),
+});
+export const AttachDownloadSchema = z.object({
+    id: z.string().trim().min(1, 'Attachment ID is required'),
+    output: z.string().trim().optional(),
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jira-ai",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "AI friendly Jira CLI to save context",
   "type": "module",
   "main": "dist/cli.js",

package/settings.yaml

@@ -14,3 +14,12 @@ commands:
   - run-jql
   - list-issue-types
   - project-statuses
+
+# Saved Queries: Define reusable JQL queries by name.
+# Keys must be lowercase alphanumeric with optional hyphens (e.g., "my-query").
+# Values are JQL query strings. Saved queries are used with:
+#   jira-ai issue search --query <name>
+#   jira-ai issue search --list-queries
+# saved-queries:
+#   my-open-bugs: "project = PROJ AND status = Open AND issuetype = Bug"
+#   overdue-tasks: "project = PROJ AND duedate < now() AND status != Done"