@stravica-ai/digital-operator-pa 0.1.39 → 0.1.41

package/dist/engineering-pa-core-extensions-atlassian/src/jira/commands/boards.mjs

@@ -0,0 +1,88 @@
+// boards.mjs - List Jira boards.
+//
+// Usage:
+//   jira boards [--project KEY]
+//
+// Fetches boards via offset pagination from the Agile API.
+// Optional --project filters server-side by project key or ID.
+// Exit 0 on success, 2 on API error.
+
+import { createClient, JiraError } from '../client.mjs';
+import { formatTable, bold, dim } from '../format.mjs';
+
+const HELP = `jira boards - List Jira boards
+
+Usage:
+  jira boards [--project KEY]
+
+Options:
+  --project KEY   Filter boards by project key or ID (server-side)
+  --help, -h      Show this help
+`;
+
+/**
+ * Run the boards command.
+ *
+ * @param {string[]} argv  Remaining args after 'boards'
+ * @param {object} [deps]  Dependency overrides
+ * @returns {Promise<number>}  Exit code
+ */
+export async function run(argv = [], deps = {}) {
+  const log = deps.log || console.log;
+  const logError = deps.logError || console.error;
+
+  if (argv.includes('--help') || argv.includes('-h')) {
+    log(HELP);
+    return 0;
+  }
+
+  // Parse --project
+  let projectKey = null;
+  const projIdx = argv.indexOf('--project');
+  if (projIdx !== -1 && projIdx + 1 < argv.length) {
+    projectKey = argv[projIdx + 1];
+  }
+
+  const client = deps.client || createClient();
+
+  try {
+    const params = {};
+    if (projectKey) {
+      params.projectKeyOrId = projectKey;
+    }
+
+    const boards = [];
+    for await (const board of client.paginateOffset('/rest/agile/1.0/board', params)) {
+      boards.push(board);
+    }
+
+    if (boards.length === 0) {
+      log(dim(projectKey ? `No boards found for project ${projectKey}.` : 'No boards found.'));
+      return 0;
+    }
+
+    const rows = boards.map((b) => ({
+      id: String(b.id || ''),
+      name: b.name || '',
+      type: b.type || '',
+      project: b.location?.projectKey || b.location?.name || '',
+    }));
+
+    const label = projectKey ? `Boards for ${projectKey}` : 'Boards';
+    log(bold(label) + dim(` (${boards.length})\n`));
+    log(formatTable(rows, [
+      { key: 'id', label: 'ID', width: 8, align: 'right' },
+      { key: 'name', label: 'Name', width: 40 },
+      { key: 'type', label: 'Type', width: 12 },
+      { key: 'project', label: 'Project', width: 16 },
+    ]));
+
+    return 0;
+  } catch (err) {
+    if (err instanceof JiraError) {
+      logError(`Failed to list boards: ${err.message}`);
+      return err.exitCode;
+    }
+    throw err;
+  }
+}

package/dist/engineering-pa-core-extensions-atlassian/src/jira/commands/bulk-transition.mjs

@@ -0,0 +1,223 @@
+// bulk-transition.mjs - Bulk-transition Jira issues via the Bulk Transition API.
+//
+// Usage:
+//   jira bulk-transition --jql "project = AI AND status = Open" --to "Cancelled"
+//   jira bulk-transition --jql "..." --to "Cancelled" --dry-run
+//
+// Flow:
+//   1. JQL search to collect issue IDs
+//   2. GET /rest/api/3/bulk/issues/transition - available common transitions
+//   3. Match target status name to a transition ID
+//   4. POST /rest/api/3/bulk/issues/transition - execute bulk transition
+//   5. Poll GET /rest/api/3/task/{taskId} until complete
+//   6. Report results
+//
+// --dry-run stops after step 3 (shows what would happen without executing).
+//
+// Exit 0 on success, 1 on usage error, 2 on API/logical error.
+
+import { createClient, JiraError } from '../client.mjs';
+import { bold, green, yellow, red, dim, cyan } from '../format.mjs';
+
+const HELP = `jira bulk-transition - Bulk-transition Jira issues
+
+Usage:
+  jira bulk-transition --jql <JQL> --to <STATUS>
+
+Options:
+  --jql <query>     JQL to select issues (required)
+  --to <status>     Target status name (required, case-insensitive match)
+  --dry-run         Show what would happen without executing the transition
+  --help, -h        Show this help
+
+Flow:
+  1. Search for issues matching the JQL
+  2. Fetch available bulk transitions for those issues
+  3. Match the target status to a transition
+  4. Execute the bulk transition (skipped with --dry-run)
+  5. Poll for completion and report results
+
+Examples:
+  jira bulk-transition --jql "project = AI AND status = Open" --to "Cancelled"
+  jira bulk-transition --jql "project = AI AND status != Done" --to Done --dry-run
+`;
+
+// Default poll interval and max attempts for task completion
+const POLL_INTERVAL_MS = 2000;
+const MAX_POLL_ATTEMPTS = 60; // 2 minutes at 2s intervals
+
+/**
+ * Run the bulk-transition command.
+ *
+ * @param {string[]} argv  Remaining args after 'bulk-transition'
+ * @param {object} [deps]  Dependency overrides
+ * @returns {Promise<number>}  Exit code
+ */
+export async function run(argv = [], deps = {}) {
+  const log = deps.log || console.log;
+  const logError = deps.logError || console.error;
+  const { parseArgs } = await import('../cli.mjs');
+  const args = parseArgs(argv);
+
+  if (args.help || args.h) {
+    log(HELP);
+    return 0;
+  }
+
+  const jql = args.jql;
+  const targetStatus = args.to;
+  const dryRun = !!args['dry-run'];
+
+  if (!jql || !targetStatus) {
+    logError('Usage: jira bulk-transition --jql <JQL> --to <STATUS>');
+    logError('Run "jira bulk-transition --help" for details.');
+    return 1;
+  }
+
+  const client = deps.client || createClient();
+  const sleep = deps.sleep || defaultSleep;
+  const pollIntervalMs = deps.pollIntervalMs ?? POLL_INTERVAL_MS;
+  const maxPollAttempts = deps.maxPollAttempts ?? MAX_POLL_ATTEMPTS;
+
+  try {
+    // Step 1: JQL search to collect issue IDs
+    log(dim(`Searching: ${jql}`));
+
+    const issueIds = [];
+    const issueKeys = [];
+    for await (const issue of client.paginateToken(
+      '/rest/api/3/search/jql',
+      { jql, fields: ['summary', 'status'] }
+    )) {
+      issueIds.push(issue.id);
+      issueKeys.push(issue.key);
+    }
+
+    if (issueIds.length === 0) {
+      log(yellow('No issues matched the JQL query.'));
+      return 0;
+    }
+
+    log(`Found ${bold(String(issueIds.length))} issue(s): ${issueKeys.slice(0, 10).join(', ')}${issueIds.length > 10 ? ` ... (+${issueIds.length - 10} more)` : ''}`);
+
+    // Step 2: GET available bulk transitions
+    const idsParam = issueIds.join(',');
+    const { data: transData } = await client.get(
+      `/rest/api/3/bulk/issues/transition?issueIds=${encodeURIComponent(idsParam)}`
+    );
+
+    const transitions = transData.transitions || [];
+    if (transitions.length === 0) {
+      logError(red('No common transitions available for the selected issues.'));
+      logError(dim('This can happen when issues span different workflows or are already in a terminal state.'));
+      return 2;
+    }
+
+    // Step 3: Match target status to a transition
+    const target = targetStatus.toLowerCase();
+    const matches = transitions.filter((t) => {
+      const name = (t.name || '').toLowerCase();
+      return name === target || name.includes(target);
+    });
+
+    let matched;
+    if (matches.length === 0) {
+      logError(`No transition matching "${targetStatus}" found.`);
+      logError('Available transitions:');
+      for (const t of transitions) {
+        logError(`  - ${t.name} (id: ${t.id})`);
+      }
+      return 1;
+    } else if (matches.length > 1) {
+      // Prefer exact match
+      const exact = matches.find((t) => (t.name || '').toLowerCase() === target);
+      if (exact) {
+        matched = exact;
+      } else {
+        logError(`Ambiguous transition "${targetStatus}" - multiple matches:`);
+        for (const t of matches) {
+          logError(`  - ${t.name} (id: ${t.id})`);
+        }
+        return 1;
+      }
+    } else {
+      matched = matches[0];
+    }
+
+    log(`Matched transition: ${bold(matched.name)} (id: ${matched.id})`);
+
+    // Dry run stops here
+    if (dryRun) {
+      log(yellow(`\n[DRY RUN] Would transition ${issueIds.length} issue(s) to "${matched.name}".`));
+      log(dim('No changes have been made. Remove --dry-run to execute.'));
+      return 0;
+    }
+
+    // Step 4: POST bulk transition
+    log(dim(`Executing bulk transition to "${matched.name}"...`));
+
+    const { data: postData } = await client.post(
+      '/rest/api/3/bulk/issues/transition',
+      { issueIds, transitionId: matched.id }
+    );
+
+    const taskId = postData.taskId;
+    if (!taskId) {
+      logError(red('Bulk transition API did not return a taskId.'));
+      return 2;
+    }
+
+    log(dim(`Task ID: ${taskId} - polling for completion...`));
+
+    // Step 5: Poll for completion
+    let taskResult = null;
+    for (let attempt = 0; attempt < maxPollAttempts; attempt++) {
+      await sleep(pollIntervalMs);
+
+      const { data: taskData } = await client.get(
+        `/rest/api/3/task/${encodeURIComponent(taskId)}`
+      );
+
+      if (taskData.status === 'COMPLETE' || taskData.status === 'DEAD' || taskData.status === 'FAILED') {
+        taskResult = taskData;
+        break;
+      }
+
+      // Show progress if available
+      if (taskData.progress !== undefined) {
+        log(dim(`  Progress: ${taskData.progress}%`));
+      }
+    }
+
+    if (!taskResult) {
+      logError(yellow('Timed out waiting for bulk transition to complete.'));
+      logError(dim(`Task ${taskId} may still be running. Check Jira or poll manually.`));
+      return 2;
+    }
+
+    // Step 6: Report results
+    if (taskResult.status === 'COMPLETE') {
+      log(green(`\nBulk transition complete: ${issueIds.length} issue(s) transitioned to "${matched.name}".`));
+    } else {
+      logError(red(`\nBulk transition ${taskResult.status.toLowerCase()}.`));
+      if (taskResult.message) {
+        logError(dim(taskResult.message));
+      }
+      return 2;
+    }
+
+    return 0;
+  } catch (err) {
+    if (err instanceof JiraError) {
+      logError(`jira bulk-transition: ${err.message}`);
+      return err.exitCode;
+    }
+    throw err;
+  }
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────
+
+function defaultSleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}

package/dist/engineering-pa-core-extensions-atlassian/src/jira/commands/cancel.mjs

@@ -0,0 +1,135 @@
+// cancel.mjs - Convenience wrapper that transitions an issue to "Cancelled".
+//
+// Equivalent to `jira transition <KEY> Cancelled`, but with a clearer
+// error message when the current workflow state has no Cancelled transition:
+// exit code 2 (logical), the available transitions are listed, and (when
+// recognisable) a likely terminal alternative is suggested.
+
+import { createClient, JiraError } from '../client.mjs';
+import { bold, green, yellow, dim } from '../format.mjs';
+import { notifyWorkspaceAsync } from '../invalidate.mjs';
+
+const HELP = `jira cancel - Transition an issue to Cancelled
+
+Usage:
+  jira cancel <KEY>
+
+Arguments:
+  KEY    Issue key (e.g. DO-1391)
+
+Wraps the Cancelled transition. If the issue's current workflow state has
+no Cancelled transition available, exits with code 2 and lists the
+transitions that are available so you can pick the right one.
+
+Examples:
+  jira cancel DO-1391
+`;
+
+// Names that indicate a "terminal / abandoned" outcome - used to suggest an
+// alternative when Cancelled itself isn't reachable from the current state.
+const TERMINAL_HINTS = [
+  'cancelled', 'canceled', 'abandoned', 'rejected', 'closed', 'won\'t do',
+  "won't do", 'wontfix', 'won\'t fix', "won't fix", 'declined',
+];
+
+/**
+ * Run the cancel command.
+ *
+ * @param {string[]} argv  Remaining args after 'cancel'
+ * @param {object} [deps]  Dependency overrides
+ * @returns {Promise<number>}  Exit code
+ */
+export async function run(argv = [], deps = {}) {
+  const log = deps.log || console.log;
+  const logError = deps.logError || console.error;
+  const { parseArgs } = await import('../cli.mjs');
+  const args = parseArgs(argv);
+
+  if (args.help || args.h) {
+    log(HELP);
+    return 0;
+  }
+
+  const key = args._[0];
+  if (!key) {
+    logError('Usage: jira cancel <KEY>');
+    return 1;
+  }
+
+  const client = deps.client || createClient();
+
+  try {
+    // Current status (for the success message)
+    const { data: issueData } = await client.get(
+      `/rest/api/3/issue/${encodeURIComponent(key)}?fields=status`
+    );
+    const currentStatus = issueData?.fields?.status?.name || 'Unknown';
+
+    // Available transitions
+    const { data: transData } = await client.get(
+      `/rest/api/3/issue/${encodeURIComponent(key)}/transitions`
+    );
+    const transitions = transData?.transitions || [];
+
+    if (transitions.length === 0) {
+      throw new JiraError(
+        `No transitions available for ${key} (current status: ${currentStatus})`,
+        2
+      );
+    }
+
+    // Look for a "Cancelled"-named transition (case-insensitive exact match).
+    const target = 'cancelled';
+    const exact = transitions.find(
+      (t) => (t.name || '').toLowerCase() === target
+    );
+
+    if (!exact) {
+      // Build a helpful error: list the available transitions and, if any
+      // look terminal/abandoned, surface them as suggestions.
+      const names = transitions.map((t) => t.name).filter(Boolean);
+      const suggestions = names.filter((n) =>
+        TERMINAL_HINTS.includes(n.toLowerCase())
+      );
+
+      logError(
+        yellow(
+          `No "Cancelled" transition available for ${key} ` +
+          `(current status: ${currentStatus}).`
+        )
+      );
+      logError('Available transitions:');
+      for (const t of transitions) {
+        logError(`  - ${t.name} (id: ${t.id})`);
+      }
+      if (suggestions.length > 0) {
+        logError(
+          dim(
+            `\nLikely alternative${suggestions.length > 1 ? 's' : ''}: ` +
+            suggestions.map((s) => `jira transition ${key} "${s}"`).join(' | ')
+          )
+        );
+      }
+      throw new JiraError(
+        `Cancelled is not an available transition for ${key} from "${currentStatus}"`,
+        2
+      );
+    }
+
+    // Execute
+    await client.post(
+      `/rest/api/3/issue/${encodeURIComponent(key)}/transitions`,
+      { transition: { id: exact.id } }
+    );
+
+    log(green(`${bold(key)}: ${currentStatus} → ${exact.name}`));
+    (deps.notifyWorkspace || notifyWorkspaceAsync)();
+    return 0;
+  } catch (err) {
+    if (err instanceof JiraError) {
+      logError(`jira cancel: ${err.message}`);
+      return err.exitCode;
+    }
+    throw err;
+  }
+}

package/dist/engineering-pa-core-extensions-atlassian/src/jira/commands/comment.mjs

@@ -0,0 +1,169 @@
+// comment.mjs - Add or list comments on a Jira issue.
+//
+// Usage:
+//   jira comment <KEY> <TEXT...>        Add a comment
+//   jira comment <KEY> -- <TEXT...>     Add a comment (text after --)
+//   jira comment <KEY> --list           List recent comments
+//
+// Exit 0 on success, 1 on usage error, 2 on API error.
+
+import { createClient, JiraError } from '../client.mjs';
+import { textToAdf, adfToText } from '../adf.mjs';
+import { formatComment, bold, dim, green } from '../format.mjs';
+import { notifyWorkspaceAsync } from '../invalidate.mjs';
+
+const HELP = `jira comment - Add or list comments on a Jira issue
+
+Usage:
+  jira comment <KEY> <TEXT>          Add a comment to an issue
+  jira comment <KEY> -- <TEXT>       Add a comment (text after --)
+  jira comment <KEY> --list          List recent comments
+
+Options:
+  --list          List the 10 most recent comments instead of adding one
+  --help, -h      Show this help
+`;
+
+/**
+ * Parse argv for the comment command.
+ * Handles -- separator for comment text, --list flag, and positional args.
+ *
+ * @param {string[]} argv  Args after 'comment'
+ * @returns {{ key: string|null, text: string|null, list: boolean }}
+ */
+function parseCommentArgs(argv) {
+  let key = null;
+  let list = false;
+  const textParts = [];
+  let afterDash = false;
+
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--') {
+      afterDash = true;
+      continue;
+    }
+    if (afterDash) {
+      textParts.push(argv[i]);
+      continue;
+    }
+    if (argv[i] === '--list') {
+      list = true;
+      continue;
+    }
+    if (argv[i] === '--help' || argv[i] === '-h') {
+      return { key: null, text: null, list: false, help: true };
+    }
+    // First positional is the key
+    if (!key) {
+      key = argv[i];
+    } else {
+      textParts.push(argv[i]);
+    }
+  }
+
+  const text = textParts.length > 0 ? textParts.join(' ') : null;
+  return { key, text, list, help: false };
+}
+
+/**
+ * Run the comment command.
+ *
+ * @param {string[]} argv  Remaining args after 'comment'
+ * @param {object} [deps]  Dependency overrides
+ * @returns {Promise<number>}  Exit code
+ */
+export async function run(argv = [], deps = {}) {
+  const log = deps.log || console.log;
+  const logError = deps.logError || console.error;
+
+  const { key, text, list, help } = parseCommentArgs(argv);
+
+  if (help) {
+    log(HELP);
+    return 0;
+  }
+
+  if (!key) {
+    logError('Usage: jira comment <KEY> <TEXT>\n       jira comment <KEY> --list');
+    return 1;
+  }
+
+  const client = deps.client || createClient();
+
+  if (list) {
+    return listComments(client, key, log, logError);
+  }
+
+  if (!text) {
+    logError('Usage: jira comment <KEY> <TEXT>\nProvide comment text as arguments or after --');
+    return 1;
+  }
+
+  const code = await addComment(client, key, text, log, logError);
+  if (code === 0) {
+    (deps.notifyWorkspace || notifyWorkspaceAsync)();
+  }
+  return code;
+}
+
+/**
+ * List recent comments on an issue.
+ */
+async function listComments(client, key, log, logError) {
+  try {
+    const { data } = await client.get(
+      `/rest/api/3/issue/${encodeURIComponent(key)}/comment?orderBy=-created&maxResults=10`
+    );
+
+    const comments = data.comments || [];
+
+    if (comments.length === 0) {
+      log(dim(`No comments on ${key}.`));
+      return 0;
+    }
+
+    log(bold(`Comments on ${key}`) + dim(` (${comments.length} shown)\n`));
+
+    for (const comment of comments) {
+      log(formatComment(comment));
+      // Render the ADF body as plain text
+      if (comment.body) {
+        const bodyText = adfToText(comment.body);
+        if (bodyText) {
+          log(`  ${bodyText.split('\n').join('\n  ')}`);
+        }
+      }
+      log('');
+    }
+
+    return 0;
+  } catch (err) {
+    if (err instanceof JiraError) {
+      logError(`Failed to list comments on ${key}: ${err.message}`);
+      return err.exitCode;
+    }
+    throw err;
+  }
+}
+
+/**
+ * Add a comment to an issue.
+ */
+async function addComment(client, key, text, log, logError) {
+  try {
+    const adfBody = textToAdf(text);
+    const { data } = await client.post(
+      `/rest/api/3/issue/${encodeURIComponent(key)}/comment`,
+      { body: adfBody }
+    );
+
+    log(green(`Comment added to ${key}.`) + dim(` (id: ${data.id})`));
+    return 0;
+  } catch (err) {
+    if (err instanceof JiraError) {
+      logError(`Failed to add comment to ${key}: ${err.message}`);
+      return err.exitCode;
+    }
+    throw err;
+  }
+}