jira-ai 0.4.5 → 0.4.10

package/dist/cli.js

@@ -20,6 +20,7 @@ import { getIssueStatisticsCommand } from './commands/get-issue-statistics.js';
 import { getPersonWorklogCommand } from './commands/get-person-worklog.js';
 import { aboutCommand } from './commands/about.js';
 import { authCommand } from './commands/auth.js';
+import { settingsCommand } from './commands/settings.js';
 import { listOrganizations, useOrganizationCommand, removeOrganizationCommand } from './commands/organization.js';
 import { isCommandAllowed, getAllowedCommands } from './lib/settings.js';
 import { setOrganizationOverride } from './lib/jira-client.js';
@@ -78,7 +79,7 @@ function withPermission(commandName, commandFn, config = {}) {
 // Auth command (always allowed, skips validation)
 program
     .command('auth')
-    .description('Set up Jira authentication credentials')
+    .description('Set up Jira authentication credentials. Supports interactive input, raw JSON string via --from-json, or .env file via --from-file.')
     .option('--from-json <json_string>', 'Accepts a raw JSON string with credentials')
     .option('--from-file <path>', 'Accepts a path to a file (typically .env) with credentials')
     .option('--alias <alias>', 'Alias for this organization')
@@ -90,34 +91,34 @@ const org = program
     .description('Manage Jira organization profiles');
 org
     .command('list')
-    .description('Show all saved organizations')
+    .description('List all saved Jira organization profiles, showing their aliases and associated host URLs.')
     .action(() => listOrganizations());
 org
     .command('use <alias>')
-    .description('Switch the active organization')
+    .description('Switch the active Jira organization profile to the one specified by the alias.')
     .action((alias) => useOrganizationCommand(alias));
 org
     .command('remove <alias>')
-    .description('Delete an organization credentials')
+    .description('Delete the saved credentials and profile for the specified organization alias.')
     .action((alias) => removeOrganizationCommand(alias));
 org
     .command('add <alias>')
-    .description('Add a new organization')
+    .description('Interactive prompt to add a new Jira organization profile with the given alias.')
     .action((alias) => authCommand({ alias }));
 // Me command
 program
     .command('me')
-    .description('Show basic user information')
+    .description('Show profile details for the currently authenticated user, including Jira host, display name, email, account ID, status, and time zone.')
     .action(withPermission('me', meCommand));
 // Projects command
 program
     .command('projects')
-    .description('Show list of projects')
+    .description('List all accessible Jira projects showing their key, name, ID, type, and project lead.')
     .action(withPermission('projects', projectsCommand));
 // List colleagues command
 program
     .command('list-colleagues [project-key]')
-    .description('Show all colleagues in the project or organization')
+    .description('Search and list users within the organization or a specific project (if project-key is provided). Returns display name, email, and account ID.')
     .action(withPermission('list-colleagues', listColleaguesCommand, {
     validateArgs: (args) => {
         if (args[0]) {
@@ -128,7 +129,7 @@ program
 // Task with details command
 program
     .command('task-with-details <task-id>')
-    .description('Show task title, body, and comments')
+    .description('Retrieve comprehensive issue data including key, summary, status (name, category), assignee, reporter, creation/update dates, due date, labels, parent/subtasks, description, and comments. Use --include-detailed-history to fetch a chronological log of all changes including field updates and status transitions.')
     .option('--include-detailed-history', 'Include the full history of task actions')
     .option('--history-limit <number>', 'Number of history entries to show (default: 50)', '50')
     .option('--history-offset <number>', 'Number of history entries to skip (default: 0)', '0')
@@ -138,21 +139,21 @@ program
 // Project statuses command
 program
     .command('project-statuses <project-id>')
-    .description('Show all possible statuses for a project')
+    .description('Fetch all available workflow statuses for a given project. Returns status name, ID, category (To Do, In Progress, Done), and description.')
     .action(withPermission('project-statuses', projectStatusesCommand, {
     validateArgs: (args) => validateOptions(ProjectKeySchema, args[0])
 }));
 // List issue types command
 program
     .command('list-issue-types <project-key>')
-    .description('Show all issue types for a project')
+    .description('List all issue types (Standard and Subtask) available for a project, providing their name, ID, hierarchy level, and description.')
     .action(withPermission('list-issue-types', listIssueTypesCommand, {
     validateArgs: (args) => validateOptions(ProjectKeySchema, args[0])
 }));
 // Run JQL command
 program
     .command('run-jql <jql-query>')
-    .description('Execute JQL query and display results')
+    .description('Execute a Jira Query Language (JQL) search. Returns a list of issues with their key, summary, status, assignee, and priority. Supports limiting results via --limit (default 50).')
     .option('-l, --limit <number>', 'Maximum number of results (default: 50)', '50')
     .action(withPermission('run-jql', runJqlCommand, {
     schema: RunJqlSchema,
@@ -165,7 +166,7 @@ program
 // Update description command
 program
     .command('update-description <task-id>')
-    .description('Update task description from a Markdown file')
+    .description('Update a Jira task\'s description using content from a local Markdown file. Requires the task ID and a valid file path.')
     .requiredOption('--from-file <path>', 'Path to Markdown file')
     .action(withPermission('update-description', updateDescriptionCommand, {
     schema: UpdateDescriptionSchema,
@@ -174,14 +175,14 @@ program
 // Add comment command
 program
     .command('add-comment')
-    .description('Add a comment to a Jira issue from a Markdown file')
+    .description('Add a new comment to a Jira issue using content from a local Markdown file. Requires the issue key and a valid file path.')
     .requiredOption('--file-path <path>', 'Path to Markdown file')
     .requiredOption('--issue-key <key>', 'Jira issue key (e.g., PS-123)')
     .action(withPermission('add-comment', addCommentCommand, { schema: AddCommentSchema }));
 // Add label command
 program
     .command('add-label-to-issue <task-id> <labels>')
-    .description('Add one or more labels to a Jira issue (comma-separated)')
+    .description('Add one or more labels (comma-separated) to a specific Jira issue.')
     .action(withPermission('add-label-to-issue', addLabelCommand, {
     validateArgs: (args) => {
         validateOptions(IssueKeySchema, args[0]);
@@ -193,7 +194,7 @@ program
 // Delete label command
 program
     .command('delete-label-from-issue <task-id> <labels>')
-    .description('Remove one or more labels from a Jira issue (comma-separated)')
+    .description('Remove one or more labels (comma-separated) from a specific Jira issue.')
     .action(withPermission('delete-label-from-issue', deleteLabelCommand, {
     validateArgs: (args) => {
         validateOptions(IssueKeySchema, args[0]);
@@ -205,7 +206,7 @@ program
 // Create task command
 program
     .command('create-task')
-    .description('Create a new Jira issue')
+    .description('Create a new Jira issue with specified title, project key, and issue type. Optional --parent key for subtasks. Returns the key of the newly created issue.')
     .requiredOption('--title <title>', 'Issue title/summary')
     .requiredOption('--project <project>', 'Project key (e.g., PROJ)')
     .requiredOption('--issue-type <type>', 'Issue type (e.g., Task, Epic, Subtask)')
@@ -214,19 +215,19 @@ program
 // Transition command
 program
     .command('transition <task-id> <to-status>')
-    .description('Transition a Jira task to a new status')
+    .description('Change the status of a Jira task. The <to-status> can be either the status name or ID.')
     .action(withPermission('transition', transitionCommand, {
     validateArgs: (args) => validateOptions(IssueKeySchema, args[0])
 }));
 // Get issue statistics command
 program
     .command('get-issue-statistics <task-ids>')
-    .description('Show time metrics and lifecycle of issues (comma-separated keys)')
+    .description('Calculate and display time-based metrics for one or more issues (comma-separated). Returns a table containing key, summary, total time logged, original estimate, and a detailed breakdown of duration spent in each status.')
     .action(withPermission('get-issue-statistics', getIssueStatisticsCommand));
 // Get person worklog command
 program
     .command('get-person-worklog <person> <timeframe>')
-    .description('Retrieve and display worklogs for a specific person within a given timeframe')
+    .description('Retrieve worklogs for a specific user over a timeframe (e.g., \'7d\', \'2w\'). Returns a list of entries with date, issue key, summary, time spent, and comments. Supports --group-by-issue.')
     .option('--group-by-issue', 'Group the output by issue')
     .action(withPermission('get-person-worklog', getPersonWorklogCommand, {
     schema: GetPersonWorklogSchema,
@@ -239,6 +240,38 @@ program
     .command('about')
     .description('Show information about the tool')
     .action(aboutCommand);
+// Settings command
+program
+    .command('settings')
+    .description('View, validate, or apply configuration settings. Use `settings` to view active config, `--validate <file>` to check a YAML file, or `--apply <file>` to update `~/.jira-ai/settings.yaml`.')
+    .option('--apply <path>', 'Validate and apply settings from a YAML file')
+    .option('--validate <path>', 'Perform schema and deep validation of a settings YAML file')
+    .addHelpText('after', `
+Examples:
+  $ jira-ai settings
+  $ jira-ai settings --validate my-settings.yaml
+  $ jira-ai settings --apply my-settings.yaml
+
+Settings File Structure:
+  projects:
+    - all                       # Allow all projects
+    - PROJ                      # Allow specific project by key
+    - key: PM                   # Project-specific configuration
+      commands:                 # Limit commands for this project
+        - task-with-details
+      filters:
+        participated:           # Filter by user participation
+          was_assignee: true
+          was_reporter: true
+          was_commenter: true
+          is_watcher: true
+        jql: "issuetype = Bug"  # Custom JQL filter
+  commands:
+    - all                       # Allow all commands globally
+    - me
+    - projects
+`)
+    .action((options) => settingsCommand(options));
 /**
  * Configure command visibility based on auth status and settings
  */

package/dist/commands/add-comment.js

@@ -2,7 +2,7 @@ import chalk from 'chalk';
 import * as fs from 'fs';
 import * as path from 'path';
 import { markdownToAdf } from 'marklassian';
-import { addIssueComment } from '../lib/jira-client.js';
+import { addIssueComment, validateIssuePermissions } from '../lib/jira-client.js';
 import { CommandError } from '../lib/errors.js';
 import { ui } from '../lib/ui.js';
 import { validateOptions, AddCommentSchema } from '../lib/validation.js';
@@ -36,6 +36,9 @@ export async function addCommentCommand(options) {
             hints: ['Ensure the Markdown content is valid.']
         });
     }
+    // Check permissions and filters
+    ui.startSpinner(`Validating permissions for ${issueKey}...`);
+    await validateIssuePermissions(issueKey, 'add-comment');
     // Add comment with spinner
     ui.startSpinner(`Adding comment to ${issueKey}...`);
     try {
@@ -44,6 +47,8 @@ export async function addCommentCommand(options) {
         console.log(chalk.gray(`\nFile: ${absolutePath}`));
     }
     catch (error) {
+        if (error instanceof CommandError)
+            throw error;
         const errorMsg = error.message?.toLowerCase() || '';
         const hints = [];
         if (errorMsg.includes('404')) {

package/dist/commands/add-label.js

@@ -1,5 +1,5 @@
 import chalk from 'chalk';
-import { addIssueLabels } from '../lib/jira-client.js';
+import { addIssueLabels, validateIssuePermissions } from '../lib/jira-client.js';
 import { CommandError } from '../lib/errors.js';
 import { ui } from '../lib/ui.js';
 import { validateOptions, IssueKeySchema } from '../lib/validation.js';
@@ -14,13 +14,19 @@ export async function addLabelCommand(taskId, labelsString) {
     if (labels.length === 0) {
         throw new CommandError('No valid labels provided');
     }
+    // Check permissions and filters
+    ui.startSpinner(`Validating permissions for ${taskId}...`);
+    await validateIssuePermissions(taskId, 'add-label-to-issue');
     ui.startSpinner(`Adding labels to ${taskId}...`);
     try {
         await addIssueLabels(taskId, labels);
         ui.succeedSpinner(chalk.green(`Labels added successfully to ${taskId}`));
-        console.log(chalk.gray(`\nLabels: ${labels.join(', ')}`));
+        console.log(chalk.gray(`
+Labels: ${labels.join(', ')}`));
     }
     catch (error) {
+        if (error instanceof CommandError)
+            throw error;
         const errorMsg = error.message?.toLowerCase() || '';
         const hints = [];
         if (errorMsg.includes('404')) {

package/dist/commands/create-task.js

@@ -3,10 +3,19 @@ import { createIssue } from '../lib/jira-client.js';
 import { CommandError } from '../lib/errors.js';
 import { ui } from '../lib/ui.js';
 import { validateOptions, CreateTaskSchema } from '../lib/validation.js';
+import { isCommandAllowed, isProjectAllowed } from '../lib/settings.js';
 export async function createTaskCommand(options) {
     // Validate options
     validateOptions(CreateTaskSchema, options);
     const { title, project, issueType, parent } = options;
+    // Check if project is allowed
+    if (!isProjectAllowed(project)) {
+        throw new CommandError(`Project '${project}' is not allowed by your settings.`);
+    }
+    // Check if command is allowed for this project
+    if (!isCommandAllowed('create-task', project)) {
+        throw new CommandError(`Command 'create-task' is not allowed for project ${project}.`);
+    }
     // Create issue with spinner
     ui.startSpinner(`Creating ${issueType} in project ${project}...`);
     try {

package/dist/commands/delete-label.js

@@ -1,5 +1,5 @@
 import chalk from 'chalk';
-import { removeIssueLabels } from '../lib/jira-client.js';
+import { removeIssueLabels, validateIssuePermissions } from '../lib/jira-client.js';
 import { CommandError } from '../lib/errors.js';
 import { ui } from '../lib/ui.js';
 import { validateOptions, IssueKeySchema } from '../lib/validation.js';
@@ -14,13 +14,19 @@ export async function deleteLabelCommand(taskId, labelsString) {
     if (labels.length === 0) {
         throw new CommandError('No valid labels provided');
     }
+    // Check permissions and filters
+    ui.startSpinner(`Validating permissions for ${taskId}...`);
+    await validateIssuePermissions(taskId, 'delete-label-from-issue');
     ui.startSpinner(`Removing labels from ${taskId}...`);
     try {
         await removeIssueLabels(taskId, labels);
         ui.succeedSpinner(chalk.green(`Labels removed successfully from ${taskId}`));
-        console.log(chalk.gray(`\nLabels: ${labels.join(', ')}`));
+        console.log(chalk.gray(`
+Labels: ${labels.join(', ')}`));
     }
     catch (error) {
+        if (error instanceof CommandError)
+            throw error;
         const errorMsg = error.message?.toLowerCase() || '';
         const hints = [];
         if (errorMsg.includes('404')) {

package/dist/commands/get-issue-statistics.js

@@ -1,5 +1,5 @@
 import chalk from 'chalk';
-import { getIssueStatistics } from '../lib/jira-client.js';
+import { getIssueStatistics, validateIssuePermissions } from '../lib/jira-client.js';
 import { formatIssueStatistics } from '../lib/formatters.js';
 import { ui } from '../lib/ui.js';
 export async function getIssueStatisticsCommand(taskIds) {
@@ -12,11 +12,24 @@ export async function getIssueStatisticsCommand(taskIds) {
     const results = [];
     for (const id of ids) {
         try {
+            // Validate permissions for each issue
+            await validateIssuePermissions(id, 'get-issue-statistics');
             const stats = await getIssueStatistics(id);
             results.push(stats);
         }
         catch (error) {
-            console.error(chalk.red(`\nFailed to fetch statistics for ${id}: ${error.message}`));
+            // Skip unauthorized or not found issues, but log a message if not already handled
+            if (!(error instanceof Error))
+                continue;
+            const isPermissionError = error.message.includes('not allowed') || error.message.includes('restricted');
+            if (isPermissionError) {
+                console.warn(chalk.yellow(`
+Skipping ${id}: ${error.message}`));
+            }
+            else {
+                console.error(chalk.red(`
+Failed to fetch statistics for ${id}: ${error.message}`));
+            }
         }
     }
     if (results.length > 0) {
@@ -24,6 +37,6 @@ export async function getIssueStatisticsCommand(taskIds) {
         console.log(formatIssueStatistics(results));
     }
     else {
-        ui.failSpinner('Failed to retrieve statistics');
+        ui.failSpinner('Failed to retrieve statistics or all issues were filtered out');
     }
 }

package/dist/commands/get-person-worklog.js

@@ -1,6 +1,6 @@
 import chalk from 'chalk';
 import { ui } from '../lib/ui.js';
-import { getIssueWorklogs, getJiraClient } from '../lib/jira-client.js';
+import { searchIssuesByJql, getIssueWorklogs } from '../lib/jira-client.js';
 import { parseTimeframe, formatDateForJql } from '../lib/utils.js';
 import { formatWorklogs } from '../lib/formatters.js';
 import { CommandError } from '../lib/errors.js';
@@ -13,14 +13,7 @@ export async function getPersonWorklogCommand(person, timeframe, options) {
         // 1. Search for issues where the person has tracked time in the timeframe
         // We use a broader search first to find relevant issues
         const jql = `worklogAuthor = "${person}" AND worklogDate >= "${startJql}" AND worklogDate <= "${endJql}"`;
-        // We need to fetch issues with their summaries
-        const client = getJiraClient();
-        const issueResponse = await client.issueSearch.searchForIssuesUsingJqlEnhancedSearch({
-            jql,
-            fields: ['summary'],
-            maxResults: 100,
-        });
-        const issues = issueResponse.issues || [];
+        const issues = await searchIssuesByJql(jql, 100);
         if (issues.length === 0) {
             ui.stopSpinner();
             console.log(chalk.yellow(`
@@ -41,7 +34,7 @@ No worklogs found for ${person} between ${startJql} and ${endJql}.
             filteredWorklogs.forEach(w => {
                 allWorklogs.push({
                     ...w,
-                    summary: issue.fields?.summary || '',
+                    summary: issue.summary || '',
                 });
             });
         }

package/dist/commands/list-colleagues.js

@@ -2,7 +2,17 @@ import chalk from 'chalk';
 import { getUsers } from '../lib/jira-client.js';
 import { formatUsers } from '../lib/formatters.js';
 import { ui } from '../lib/ui.js';
+import { isCommandAllowed, isProjectAllowed } from '../lib/settings.js';
+import { CommandError } from '../lib/errors.js';
 export async function listColleaguesCommand(projectKey) {
+    if (projectKey) {
+        if (!isProjectAllowed(projectKey)) {
+            throw new CommandError(`Project '${projectKey}' is not allowed by your settings.`);
+        }
+        if (!isCommandAllowed('list-colleagues', projectKey)) {
+            throw new CommandError(`Command 'list-colleagues' is not allowed for project ${projectKey}.`);
+        }
+    }
     const message = projectKey
         ? `Fetching colleagues for project ${projectKey}...`
         : 'Fetching all active colleagues...';

package/dist/commands/list-issue-types.js

@@ -2,7 +2,17 @@ import chalk from 'chalk';
 import { getProjectIssueTypes } from '../lib/jira-client.js';
 import { formatProjectIssueTypes } from '../lib/formatters.js';
 import { ui } from '../lib/ui.js';
+import { isCommandAllowed, isProjectAllowed } from '../lib/settings.js';
+import { CommandError } from '../lib/errors.js';
 export async function listIssueTypesCommand(projectKey) {
+    // Check if project is allowed
+    if (!isProjectAllowed(projectKey)) {
+        throw new CommandError(`Project '${projectKey}' is not allowed by your settings.`);
+    }
+    // Check if command is allowed for this project
+    if (!isCommandAllowed('list-issue-types', projectKey)) {
+        throw new CommandError(`Command 'list-issue-types' is not allowed for project ${projectKey}.`);
+    }
     ui.startSpinner(`Fetching issue types for project ${projectKey}...`);
     const issueTypes = await getProjectIssueTypes(projectKey);
     ui.succeedSpinner(chalk.green('Issue types retrieved'));

package/dist/commands/project-statuses.js

@@ -2,9 +2,25 @@ import chalk from 'chalk';
 import { getProjectStatuses } from '../lib/jira-client.js';
 import { formatProjectStatuses } from '../lib/formatters.js';
 import { ui } from '../lib/ui.js';
-export async function projectStatusesCommand(projectId) {
-    ui.startSpinner(`Fetching statuses for project ${projectId}...`);
-    const statuses = await getProjectStatuses(projectId);
-    ui.succeedSpinner(chalk.green('Project statuses retrieved'));
-    console.log(formatProjectStatuses(projectId, statuses));
+import { isCommandAllowed, isProjectAllowed } from '../lib/settings.js';
+import { CommandError } from '../lib/errors.js';
+export async function projectStatusesCommand(projectIdOrKey) {
+    // Check if project is allowed
+    if (!isProjectAllowed(projectIdOrKey)) {
+        throw new CommandError(`Project '${projectIdOrKey}' is not allowed by your settings.`);
+    }
+    // Check if command is allowed for this project
+    if (!isCommandAllowed('project-statuses', projectIdOrKey)) {
+        throw new CommandError(`Command 'project-statuses' is not allowed for project ${projectIdOrKey}.`);
+    }
+    ui.startSpinner(`Fetching statuses for project ${projectIdOrKey}...`);
+    try {
+        const statuses = await getProjectStatuses(projectIdOrKey);
+        ui.succeedSpinner(chalk.green('Project statuses retrieved'));
+        console.log(formatProjectStatuses(projectIdOrKey, statuses));
+    }
+    catch (error) {
+        ui.failSpinner(chalk.red('Failed to fetch project statuses'));
+        throw error;
+    }
 }

package/dist/commands/projects.js

@@ -6,15 +6,17 @@ import { ui } from '../lib/ui.js';
 export async function projectsCommand() {
     ui.startSpinner('Fetching projects...');
     const allProjects = await getProjects();
-    const allowedProjectKeys = getAllowedProjects();
+    const allowedProjects = getAllowedProjects();
     // Filter projects based on settings
-    const filteredProjects = allowedProjectKeys.includes('all')
+    const hasAll = allowedProjects.some(p => p === 'all');
+    const filteredProjects = hasAll
         ? allProjects
         : allProjects.filter(project => isProjectAllowed(project.key));
     ui.succeedSpinner(chalk.green('Projects retrieved'));
     if (filteredProjects.length === 0) {
         console.log(chalk.yellow('\nNo projects match your settings configuration.'));
-        console.log(chalk.gray('Allowed projects: ' + allowedProjectKeys.join(', ')));
+        const displayKeys = allowedProjects.map(p => typeof p === 'string' ? p : p.key);
+        console.log(chalk.gray('Allowed projects: ' + displayKeys.join(', ')));
     }
     else {
         console.log(formatProjects(filteredProjects));

package/dist/commands/settings.js

@@ -0,0 +1,87 @@
+import chalk from 'chalk';
+import fs from 'fs';
+import yaml from 'js-yaml';
+import { loadSettings, saveSettings } from '../lib/settings.js';
+import { formatSettings } from '../lib/formatters.js';
+import { ui } from '../lib/ui.js';
+import { SettingsSchema } from '../lib/validation.js';
+import { getProjects } from '../lib/jira-client.js';
+import { CommandError } from '../lib/errors.js';
+import { validateEnvVars } from '../lib/utils.js';
+export async function settingsCommand(options) {
+    if (options.apply) {
+        await applySettings(options.apply);
+        return;
+    }
+    if (options.validate) {
+        await validateSettingsFile(options.validate);
+        return;
+    }
+    // Default: Show current settings
+    const settings = loadSettings();
+    console.log(formatSettings(settings));
+}
+async function validateSettingsFile(filePath) {
+    ui.startSpinner(`Validating ${filePath}...`);
+    if (!fs.existsSync(filePath)) {
+        ui.failSpinner(`File not found: ${filePath}`);
+        throw new CommandError(`File not found: ${filePath}`);
+    }
+    let rawSettings;
+    try {
+        const content = fs.readFileSync(filePath, 'utf8');
+        rawSettings = yaml.load(content);
+    }
+    catch (error) {
+        ui.failSpinner(`Error parsing YAML: ${error instanceof Error ? error.message : String(error)}`);
+        throw new CommandError(`Error parsing YAML in ${filePath}`);
+    }
+    // Schema Validation
+    const result = SettingsSchema.safeParse(rawSettings);
+    if (!result.success) {
+        ui.failSpinner('Schema validation failed');
+        const messages = result.error.issues
+            .map((err) => `${err.path.join('.')}: ${err.message}`)
+            .join('\n');
+        throw new CommandError(`Invalid settings structure:\n${messages}`);
+    }
+    const settings = result.data;
+    // Deep Validation
+    ui.updateSpinner('Performing deep validation against Jira...');
+    try {
+        validateEnvVars();
+        const projects = await getProjects();
+        const projectKeys = new Set(projects.map(p => p.key));
+        for (const p of settings.projects) {
+            const key = typeof p === 'string' ? p : p.key;
+            if (key === 'all')
+                continue;
+            if (!projectKeys.has(key)) {
+                ui.failSpinner(`Deep validation failed: Project "${key}" not found in Jira.`);
+                throw new CommandError(`Project "${key}" not found in Jira.`);
+            }
+            // If project has specific commands, we could validate them too, 
+            // but they are just strings matched against command names.
+        }
+        ui.succeedSpinner(chalk.green('Settings are valid!'));
+        return settings;
+    }
+    catch (error) {
+        if (error instanceof CommandError)
+            throw error;
+        ui.failSpinner(`Deep validation failed: ${error instanceof Error ? error.message : String(error)}`);
+        throw new CommandError(`Failed to connect to Jira for validation: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+async function applySettings(filePath) {
+    const settings = await validateSettingsFile(filePath);
+    ui.startSpinner('Applying settings...');
+    try {
+        saveSettings(settings);
+        ui.succeedSpinner(chalk.green('Settings applied successfully!'));
+    }
+    catch (error) {
+        ui.failSpinner(`Error applying settings: ${error instanceof Error ? error.message : String(error)}`);
+        throw error;
+    }
+}

package/dist/commands/task-with-details.js

@@ -1,8 +1,9 @@
 import chalk from 'chalk';
-import { getTaskWithDetails } from '../lib/jira-client.js';
+import { getTaskWithDetails, getCurrentUser } from '../lib/jira-client.js';
 import { formatTaskDetails } from '../lib/formatters.js';
 import { CommandError } from '../lib/errors.js';
 import { ui } from '../lib/ui.js';
+import { isCommandAllowed, validateIssueAgainstFilters } from '../lib/settings.js';
 export async function taskWithDetailsCommand(taskId, options = {}) {
     ui.startSpinner(`Fetching details for ${taskId}...`);
     try {
@@ -11,10 +12,32 @@ export async function taskWithDetailsCommand(taskId, options = {}) {
             historyLimit: options.historyLimit ? parseInt(options.historyLimit, 10) : undefined,
             historyOffset: options.historyOffset ? parseInt(options.historyOffset, 10) : undefined,
         });
+        const projectKey = task.key.split('-')[0];
+        // Check if command is allowed for this project
+        if (!isCommandAllowed('task-with-details', projectKey)) {
+            ui.failSpinner(chalk.red('Command not allowed for this project'));
+            throw new CommandError(`Command 'task-with-details' is not allowed for project ${projectKey}.`, {
+                hints: [
+                    `Update settings.yaml to enable this command for this project.`
+                ]
+            });
+        }
+        // Check granular filters
+        const currentUser = await getCurrentUser();
+        if (!validateIssueAgainstFilters(task, currentUser.accountId)) {
+            ui.failSpinner(chalk.red('Access denied by project filters'));
+            throw new CommandError(`Access to issue ${taskId} is restricted by project filters.`, {
+                hints: [
+                    `This project has filters that you do not meet (e.g., participated roles).`
+                ]
+            });
+        }
         ui.succeedSpinner(chalk.green('Task details retrieved'));
         console.log(formatTaskDetails(task));
     }
     catch (error) {
+        if (error instanceof CommandError)
+            throw error;
         const errorMsg = error.message?.toLowerCase() || '';
         const hints = [];
         if (error.response?.status === 404 || errorMsg.includes('404')) {

package/dist/commands/transition.js

@@ -1,8 +1,11 @@
 import chalk from 'chalk';
-import { getIssueTransitions, transitionIssue } from '../lib/jira-client.js';
+import { getIssueTransitions, transitionIssue, validateIssuePermissions } from '../lib/jira-client.js';
 import { CommandError } from '../lib/errors.js';
 import { ui } from '../lib/ui.js';
 export async function transitionCommand(taskId, toStatus) {
+    // Check permissions and filters
+    ui.startSpinner(`Validating permissions for ${taskId}...`);
+    await validateIssuePermissions(taskId, 'transition');
     ui.startSpinner(`Fetching available transitions for ${taskId}...`);
     try {
         const transitions = await getIssueTransitions(taskId);

package/dist/commands/update-description.js

@@ -2,7 +2,7 @@ import chalk from 'chalk';
 import * as fs from 'fs';
 import * as path from 'path';
 import { markdownToAdf } from 'marklassian';
-import { updateIssueDescription } from '../lib/jira-client.js';
+import { updateIssueDescription, validateIssuePermissions } from '../lib/jira-client.js';
 import { CommandError } from '../lib/errors.js';
 import { ui } from '../lib/ui.js';
 import { validateOptions, UpdateDescriptionSchema, IssueKeySchema } from '../lib/validation.js';
@@ -38,14 +38,20 @@ export async function updateDescriptionCommand(taskId, options) {
             hints: ['Ensure the Markdown content is valid.']
         });
     }
+    // Check permissions and filters
+    ui.startSpinner(`Validating permissions for ${taskId}...`);
+    await validateIssuePermissions(taskId, 'update-description');
     // Update issue description with spinner
     ui.startSpinner(`Updating description for ${taskId}...`);
     try {
         await updateIssueDescription(taskId, adfContent);
         ui.succeedSpinner(chalk.green(`Description updated successfully for ${taskId}`));
-        console.log(chalk.gray(`\nFile: ${absolutePath}`));
+        console.log(chalk.gray(`
+File: ${absolutePath}`));
     }
     catch (error) {
+        if (error instanceof CommandError)
+            throw error;
         const errorMsg = error.message?.toLowerCase() || '';
         const hints = [];
         if (errorMsg.includes('404')) {

package/dist/lib/formatters.js

@@ -360,3 +360,57 @@ export function formatWorklogs(worklogs, groupByIssue = false) {
     output += chalk.bold(`Total time tracked: ${totalHours}h`) + '\n';
     return output;
 }
+/**
+ * Format settings
+ */
+export function formatSettings(settings) {
+    let output = '\n' + chalk.bold.cyan('Active Configuration') + '\n\n';
+    // Global Commands
+    output += chalk.bold('Global Commands:') + '\n';
+    output += `  ${settings.commands.join(', ')}\n\n`;
+    // Projects
+    output += chalk.bold(`Projects (${settings.projects.length}):`) + '\n';
+    const table = createTable(['Project', 'Commands', 'Filters'], [15, 30, 50]);
+    settings.projects.forEach((p) => {
+        let key;
+        let commands = 'global';
+        let filters = 'none';
+        if (typeof p === 'string') {
+            key = p;
+        }
+        else {
+            key = p.key;
+            if (p.commands) {
+                commands = p.commands.join(', ');
+            }
+            if (p.filters) {
+                const parts = [];
+                if (p.filters.jql) {
+                    parts.push(`JQL: ${p.filters.jql}`);
+                }
+                if (p.filters.participated) {
+                    const roles = [];
+                    if (p.filters.participated.was_assignee)
+                        roles.push('Assignee');
+                    if (p.filters.participated.was_reporter)
+                        roles.push('Reporter');
+                    if (p.filters.participated.was_commenter)
+                        roles.push('Commenter');
+                    if (p.filters.participated.is_watcher)
+                        roles.push('Watcher');
+                    if (roles.length > 0) {
+                        parts.push(`Roles: ${roles.join(', ')}`);
+                    }
+                }
+                filters = parts.join('\n') || 'none';
+            }
+        }
+        table.push([
+            chalk.cyan(key),
+            commands,
+            filters
+        ]);
+    });
+    output += table.toString() + '\n';
+    return output;
+}

package/dist/lib/jira-client.js

@@ -1,6 +1,8 @@
 import { Version3Client } from 'jira.js';
 import { calculateStatusStatistics, convertADFToMarkdown } from './utils.js';
 import { loadCredentials } from './auth-storage.js';
+import { applyGlobalFilters, isProjectAllowed, isCommandAllowed, validateIssueAgainstFilters } from './settings.js';
+import { CommandError } from './errors.js';
 let jiraClient = null;
 let organizationOverride = undefined;
 /**
@@ -125,12 +127,14 @@ export async function getTaskWithDetails(taskId, options = {}) {
             'parent',
             'subtasks',
             'labels',
+            'watches',
         ],
     });
     // Extract comments
     const comments = issue.fields.comment?.comments?.map((comment) => ({
         id: comment.id,
         author: {
+            accountId: comment.author?.accountId || '',
             displayName: comment.author?.displayName || 'Unknown',
             emailAddress: comment.author?.emailAddress,
         },
@@ -186,6 +190,14 @@ export async function getTaskWithDetails(taskId, options = {}) {
         // Apply offset and limit
         history = history.slice(historyOffset, historyOffset + historyLimit);
     }
+    // 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.
+    }
     return {
         id: issue.id || '',
         key: issue.key || '',
@@ -196,9 +208,11 @@ export async function getTaskWithDetails(taskId, options = {}) {
             category: issue.fields.status?.statusCategory?.key || 'unknown',
         },
         assignee: issue.fields.assignee ? {
+            accountId: issue.fields.assignee.accountId || '',
             displayName: issue.fields.assignee.displayName || 'Unknown',
         } : undefined,
         reporter: issue.fields.reporter ? {
+            accountId: issue.fields.reporter.accountId || '',
             displayName: issue.fields.reporter.displayName || 'Unknown',
         } : undefined,
         created: issue.fields.created || '',
@@ -209,6 +223,7 @@ export async function getTaskWithDetails(taskId, options = {}) {
         parent,
         subtasks,
         history,
+        watchers: issue.fields.watches?.isWatching ? ['CURRENT_USER'] : [], // Simple flag for now
     };
 }
 /**
@@ -245,8 +260,9 @@ export async function getProjectStatuses(projectIdOrKey) {
  */
 export async function searchIssuesByJql(jqlQuery, maxResults) {
     const client = getJiraClient();
+    const filteredJql = applyGlobalFilters(jqlQuery);
     const response = await client.issueSearch.searchForIssuesUsingJqlEnhancedSearch({
-        jql: jqlQuery,
+        jql: filteredJql,
         maxResults,
         fields: ['summary', 'status', 'assignee', 'priority'],
     });
@@ -335,13 +351,33 @@ export async function createIssue(projectKey, summary, issueTypeName, parentKey)
     const response = await client.issues.createIssue({
         fields,
     });
-    return {
-        key: response.key || '',
-        id: response.id || '',
-    };
+    return { key: response.key || '', id: response.id || '' };
+}
+/**
+ * Validate that the current user has permission to perform a command on an issue
+ */
+export async function validateIssuePermissions(issueKey, commandName) {
+    const task = await getTaskWithDetails(issueKey);
+    const projectKey = task.key.split('-')[0];
+    if (!isProjectAllowed(projectKey)) {
+        throw new CommandError(`Project '${projectKey}' is not allowed by your settings.`);
+    }
+    if (!isCommandAllowed(commandName, projectKey)) {
+        throw new CommandError(`Command '${commandName}' is not allowed for project ${projectKey}.`, {
+            hints: [`Update settings.yaml to enable this command for this project.`]
+        });
+    }
+    const currentUser = await getCurrentUser();
+    if (!validateIssueAgainstFilters(task, currentUser.accountId)) {
+        throw new CommandError(`Access to issue ${issueKey} is restricted by project filters.`, {
+            hints: [`This project has filters that you do not meet (e.g., participated roles).`]
+        });
+    }
+    return task;
 }
 /**
  * Add labels to a Jira issue
+
  * @param taskId - The issue key (e.g., "PROJ-123")
  * @param labels - Array of labels to add
  */

package/dist/lib/settings.js

@@ -4,6 +4,7 @@ import os from 'os';
 import yaml from 'js-yaml';
 import chalk from 'chalk';
 import { CliError } from '../types/errors.js';
+import { SettingsSchema } from './validation.js';
 const CONFIG_DIR = path.join(os.homedir(), '.jira-ai');
 const SETTINGS_FILE = path.join(CONFIG_DIR, 'settings.yaml');
 let cachedSettings = null;
@@ -31,7 +32,7 @@ export function loadSettings() {
                 console.error('Error migrating settings.yaml:', error);
                 const defaultSettings = {
                     projects: ['all'],
-                    commands: ['all']
+                    commands: ['me', 'projects', 'task-with-details', 'run-jql', 'list-issue-types', 'project-statuses', 'create-task', 'list-colleagues', 'add-comment', 'add-label', 'delete-label', 'get-issue-statistics', 'get-person-worklog', 'organization', 'transition', 'update-description']
                 };
                 cachedSettings = defaultSettings;
                 return cachedSettings;
@@ -41,7 +42,7 @@ export function loadSettings() {
             // Create default settings.yaml if it doesn't exist anywhere
             const defaultSettings = {
                 projects: ['all'],
-                commands: ['all']
+                commands: ['me', 'projects', 'task-with-details', 'run-jql', 'list-issue-types', 'project-statuses', 'create-task', 'list-colleagues', 'add-comment', 'add-label', 'delete-label', 'get-issue-statistics', 'get-person-worklog', 'organization', 'transition', 'update-description']
             };
             try {
                 const yamlStr = yaml.dump(defaultSettings);
@@ -56,26 +57,77 @@ export function loadSettings() {
     }
     try {
         const fileContents = fs.readFileSync(SETTINGS_FILE, 'utf8');
-        const settings = yaml.load(fileContents);
-        cachedSettings = {
-            projects: settings.projects || ['all'],
-            commands: settings.commands || ['all']
-        };
+        const rawSettings = yaml.load(fileContents);
+        const result = SettingsSchema.safeParse(rawSettings);
+        if (!result.success) {
+            console.warn(chalk.yellow(`Warning: ${SETTINGS_FILE} has validation errors:`));
+            result.error.issues.forEach(issue => {
+                console.warn(chalk.yellow(`  - ${issue.path.join('.')}: ${issue.message}`));
+            });
+            // Fallback to raw settings or default if parsing fails completely
+            const settings = rawSettings;
+            cachedSettings = {
+                projects: settings?.projects || ['all'],
+                commands: settings?.commands || ['me', 'projects', 'task-with-details', 'run-jql', 'list-issue-types', 'project-statuses', 'create-task', 'list-colleagues', 'add-comment', 'add-label', 'delete-label', 'get-issue-statistics', 'get-person-worklog', 'organization', 'transition', 'update-description']
+            };
+        }
+        else {
+            cachedSettings = result.data;
+        }
         return cachedSettings;
     }
     catch (error) {
         throw new CliError(`Error loading ${SETTINGS_FILE}: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
+export function saveSettings(settings) {
+    // Ensure config directory exists
+    if (!fs.existsSync(CONFIG_DIR)) {
+        fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    }
+    try {
+        const yamlStr = yaml.dump(settings);
+        fs.writeFileSync(SETTINGS_FILE, yamlStr);
+        cachedSettings = settings;
+    }
+    catch (error) {
+        throw new CliError(`Error saving ${SETTINGS_FILE}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
 export function isProjectAllowed(projectKey) {
     const settings = loadSettings();
-    if (settings.projects.includes('all')) {
-        return true;
-    }
-    return settings.projects.includes(projectKey);
+    const isAllowed = settings.projects.some(p => {
+        if (typeof p === 'string') {
+            return p === 'all' || p === projectKey;
+        }
+        return p.key === projectKey;
+    });
+    return isAllowed;
 }
-export function isCommandAllowed(commandName) {
+export function isCommandAllowed(commandName, projectKey) {
     const settings = loadSettings();
+    // about, auth, and settings are always allowed
+    if (['about', 'auth', 'settings'].includes(commandName)) {
+        return true;
+    }
+    if (projectKey) {
+        const project = settings.projects.find(p => (typeof p === 'string' ? p : p.key) === projectKey);
+        if (project && typeof project !== 'string' && project.commands) {
+            return project.commands.includes(commandName);
+        }
+    }
+    else {
+        // For visibility/global check: allowed if in global list OR in any project-specific list
+        const allowedGlobally = settings.commands.includes('all') || settings.commands.includes(commandName);
+        if (allowedGlobally) {
+            return true;
+        }
+        const allowedInAnyProject = settings.projects.some(p => typeof p !== 'string' && p.commands && p.commands.includes(commandName));
+        if (allowedInAnyProject) {
+            return true;
+        }
+        return false;
+    }
     if (settings.commands.includes('all')) {
         return true;
     }
@@ -89,6 +141,57 @@ export function getAllowedCommands() {
     const settings = loadSettings();
     return settings.commands;
 }
+export function applyGlobalFilters(jql) {
+    const settings = loadSettings();
+    const allAllowed = settings.projects.some(p => p === 'all');
+    if (allAllowed) {
+        return jql;
+    }
+    const projectFilters = settings.projects.map(p => {
+        const key = typeof p === 'string' ? p : p.key;
+        const projectJql = typeof p === 'string' ? null : p.filters?.jql;
+        if (projectJql) {
+            return `(project = "${key}" AND (${projectJql}))`;
+        }
+        else {
+            return `project = "${key}"`;
+        }
+    });
+    if (projectFilters.length === 0) {
+        return `project = "NONE" AND (${jql})`;
+    }
+    const combinedProjectFilter = `(${projectFilters.join(' OR ')})`;
+    return `(${combinedProjectFilter}) AND (${jql})`;
+}
+export function validateIssueAgainstFilters(issue, currentUserId) {
+    const settings = loadSettings();
+    const projectKey = issue.key.split('-')[0];
+    const project = settings.projects.find(p => {
+        if (typeof p === 'string')
+            return p === 'all' || p === projectKey;
+        return p.key === projectKey;
+    });
+    if (!project) {
+        return false;
+    }
+    if (typeof project === 'string')
+        return true;
+    if (project.filters?.participated) {
+        const { participated } = project.filters;
+        let hasParticipated = false;
+        if (participated.was_assignee && issue.assignee?.accountId === currentUserId)
+            hasParticipated = true;
+        if (participated.was_reporter && issue.reporter?.accountId === currentUserId)
+            hasParticipated = true;
+        if (participated.was_commenter && issue.comments?.some((c) => c.author?.accountId === currentUserId))
+            hasParticipated = true;
+        if (participated.is_watcher && issue.watchers?.includes('CURRENT_USER'))
+            hasParticipated = true;
+        if (!hasParticipated)
+            return false;
+    }
+    return true;
+}
 // For testing purposes only
 export function __resetCache__() {
     cachedSettings = null;

package/dist/lib/ui.js

@@ -26,6 +26,11 @@ class UI {
             this.spinnerInstance = null;
         }
     }
+    updateSpinner(message) {
+        if (this.spinnerInstance) {
+            this.spinnerInstance.text = message;
+        }
+    }
     get spinner() {
         return this.spinnerInstance;
     }

package/dist/lib/validation.js

@@ -72,3 +72,25 @@ export const TimeframeSchema = z.string().regex(/^\d+d$/, 'Timeframe must be in
 export const GetPersonWorklogSchema = z.object({
     groupByIssue: z.boolean().optional(),
 });
+export const ProjectFiltersSchema = z.object({
+    participated: z.object({
+        was_assignee: z.boolean().optional(),
+        was_reporter: z.boolean().optional(),
+        was_commenter: z.boolean().optional(),
+        is_watcher: z.boolean().optional(),
+    }).optional(),
+    jql: z.string().optional(),
+});
+export const ProjectConfigSchema = z.object({
+    key: z.string().trim().min(1),
+    commands: z.array(z.string()).optional(),
+    filters: ProjectFiltersSchema.optional(),
+});
+export const ProjectSettingSchema = z.union([
+    z.string().trim().min(1),
+    ProjectConfigSchema
+]);
+export const SettingsSchema = z.object({
+    projects: z.array(ProjectSettingSchema).nullish().transform(val => val || ['all']),
+    commands: z.array(z.string()).nullish().transform(val => val || ['me', 'projects', 'task-with-details', 'run-jql', 'list-issue-types', 'project-statuses', 'create-task', 'list-colleagues', 'add-comment', 'add-label', 'delete-label', 'get-issue-statistics', 'get-person-worklog', 'organization', 'transition', 'update-description']),
+});

package/package.json

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

package/settings.yaml

@@ -4,23 +4,13 @@
 # Examples: BP, PM, PS
 projects:
   - all
-  #- BP
-  #- PM
-  #- PS
-  # Uncomment below to allow all projects
-  # - all
 
 # Commands: List of allowed commands (use "all" to allow all commands)
 # Available commands: me, projects, task-with-details, project-statuses, list-issue-types, run-jql, update-description, add-comment, create-task, get-issue-statistics, about, transition, add-label-to-issue, delete-label-from-issue, list-colleagues, get-person-worklog
 commands:
   - me
-  - get-issue-statistics
-  - get-person-worklog
-  # Uncomment below to allow all commands
-  # - all
-  # - task-with-details
-  # - project-statuses
-  # - list-issue-types
-  # - update-description
-  # - add-comment
-  # - create-task
+  - projects
+  - task-with-details
+  - run-jql
+  - list-issue-types
+  - project-statuses