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

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

@@ -0,0 +1,486 @@
+// advance.mjs - Walk an issue along its configured workflow chain.
+//
+// `jira transition` moves one step and needs the exact transition verb.
+// Some Jira workflows are long chains whose verbs do not match
+// the statuses they land on ("For Merge" → Merge, "Testing Successful" →
+// Ready for PROD), so advancing a ticket several states used to mean
+// probing transitions one hop at a time. `jira advance` computes the
+// path from the chain config (the tool-shipped default, or an operator
+// override at operator/config/jira-workflow-chains.json) and executes
+// every hop, verifying the landing status after each.
+//
+// Gated steps (the AI workflow validates required fields when leaving
+// Qualification, but its transition screen rejects field flags) are
+// honoured by applying the fields via issue update BEFORE transitioning.
+//
+// Three routing modes, from the workflow-chain design:
+//
+//   --next     one forward edge, never a shortcut. "Move it on."
+//   --close    shortest route to Done, shortcuts included. "Close it."
+//   <TARGET>   route to a named status, shortcuts avoided unless the
+//              target is otherwise unreachable.
+//
+// Issue types whose status is an operator judgement rather than a
+// mechanical consequence of the work (Epics) declare a consent policy in
+// the chain config and are refused without --operator-consent.
+
+import { createClient, JiraError } from '../client.mjs';
+import { textToAdf } from '../adf.mjs';
+import { bold, green, yellow, dim, cyan } from '../format.mjs';
+import {
+  buildRequiredFieldsPatch,
+  maybeWrapRequiredFieldError,
+  discoverFieldId,
+} from '../required-fields.mjs';
+import {
+  loadChains,
+  chainsSearchPaths,
+  getChainConfig,
+  getChainEdges,
+  getConsentPolicy,
+  getTicketTypeFieldId,
+  listConfiguredIssueTypes,
+  chainStatuses,
+  resolveTargetStatus,
+  resolveDoneStatus,
+  computePath,
+  computeNextEdge,
+  isShortcutEdge,
+  reachableStatuses,
+} from '../workflow-chains.mjs';
+import { notifyWorkspaceAsync } from '../invalidate.mjs';
+
+const HELP = `jira advance - Walk an issue along its configured workflow chain
+
+Usage:
+  jira advance <KEY> <TARGET-STATUS> [--dry-run] [FIELD FLAGS]
+  jira advance <KEY> --next          [--dry-run] [FIELD FLAGS]
+  jira advance <KEY> --close         [--dry-run] [FIELD FLAGS]
+
+Arguments:
+  KEY             Issue key (e.g. AI-123)
+  TARGET-STATUS   Status to advance to (case-insensitive; unique partial
+                  match accepted, e.g. "peer" for "Peer review")
+
+Modes (exactly one; a target status and a mode flag are exclusive):
+  <TARGET-STATUS>  Route to a named status. Shortcut edges are avoided so
+                   the ticket passes through the states you asked for;
+                   they are used only if the target is otherwise
+                   unreachable.
+  --next           Advance exactly ONE forward step - the next logical
+                   status. Never takes a shortcut edge, so it cannot skip
+                   review/merge states. Refuses when the current status
+                   has more than one forward step (name the target).
+  --close          Take the most direct encoded route to Done, shortcut
+                   edges included.
+
+Options:
+  --dry-run                 Print the planned path and gate requirements
+                            without executing anything. Exits 0 when the
+                            plan is executable, 1 when gate fields are
+                            missing.
+  --operator-consent        Required for issue types whose chain declares
+                            a consent policy (Epics). Pass it only when
+                            the operator has explicitly asked for this
+                            transition.
+  --ticket-type VALUE       Set the Ticket Type select customfield (e.g.
+                            "Tech Roadmap", "Incident Response") - required
+                            by gated steps when not already populated.
+  --affected-services NAME  Set Affected services (resolved to ARI).
+  --original-estimate DUR   Set timetracking.originalEstimate ("2h", "1d").
+  --field K=V               Set an arbitrary field via update (repeatable).
+  --field-adf K=text        Set an ADF-typed field via update (repeatable).
+
+Exit codes: 0 success, 1 usage/gate, 2 chain or state problem,
+4 refused for want of operator consent.
+
+The chain is data, not code: jira-workflow-chains.json maps project + issue
+type to a list of forward edges. The tool ships a default; an estate can
+override it at operator/config/jira-workflow-chains.json, which takes
+precedence when present. Gated edges declare fields that must be populated
+BEFORE the transition (the transition screen rejects them); advance applies
+supplied field flags via issue update first, then walks the chain, verifying
+the landing status after every hop.
+
+Examples:
+  jira advance AI-123 --next
+  jira advance AI-123 --close --dry-run
+  jira advance AI-123 "In Progress"
+  jira advance AI-123 --close --ticket-type "Tech Roadmap" --original-estimate 2h
+  jira advance AI-1578 --close --operator-consent
+`;
+
+// Exit code for a transition refused because the issue type's chain
+// declares a consent policy. Distinct from 1 (usage) and 2 (chain/state)
+// so a caller can tell "you passed bad args" from "you are not allowed to
+// do this without being asked to".
+const EXIT_CONSENT_REQUIRED = 4;
+
+// Gate field kinds → how each is satisfied. `flag` is what the operator
+// passes; `describe` names the field in errors.
+const GATE_FIELD_KINDS = {
+  ticketType: { flag: '--ticket-type "<option>"', describe: 'Ticket Type' },
+  affectedServices: { flag: '--affected-services "<service>"', describe: 'Affected Services' },
+  originalEstimate: { flag: '--original-estimate <dur>', describe: 'Original Estimate' },
+};
+
+/**
+ * Run the advance command.
+ *
+ * @param {string[]} argv  Remaining args after 'advance'
+ * @param {object} [deps]  Dependency overrides (client, chains, log, logError,
+ *                         notifyWorkspace)
+ * @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];
+  const targetInput = args._.slice(1).join(' ');
+  const dryRun = Boolean(args['dry-run']);
+  const wantsNext = Boolean(args.next);
+  const wantsClose = Boolean(args.close);
+  const hasConsent = Boolean(args['operator-consent']);
+
+  // ── Mode selection ─────────────────────────────────────────────────
+  // Exactly one of: named target, --next, --close. Nothing is inferred
+  // from a missing argument - an omitted target is ambiguous input, and
+  // this command mutates, so it asks rather than guesses.
+  if (!key) {
+    logUsage(logError);
+    return 1;
+  }
+  if (wantsNext && wantsClose) {
+    logError('jira advance: --next and --close are mutually exclusive.');
+    logError('  --next  advances one step; --close goes all the way to Done.');
+    return 1;
+  }
+  if ((wantsNext || wantsClose) && targetInput) {
+    const flag = wantsNext ? '--next' : '--close';
+    logError(`jira advance: ${flag} takes no target status (got "${targetInput}").`);
+    logError('Pass a target status OR a mode flag, not both.');
+    return 1;
+  }
+  if (!wantsNext && !wantsClose && !targetInput) {
+    logError('jira advance: no target status and no mode flag.');
+    logError('  jira advance <KEY> <TARGET-STATUS>   route to a named status');
+    logError('  jira advance <KEY> --next           advance one step');
+    logError('  jira advance <KEY> --close          go to Done, shortcuts included');
+    return 1;
+  }
+  const mode = wantsNext ? 'next' : wantsClose ? 'close' : 'target';
+
+  // ── Load chain config ──────────────────────────────────────────────
+  let chains = deps.chains;
+  if (!chains) {
+    try {
+      chains = await loadChains(deps.projectRoot);
+    } catch (err) {
+      logError(`jira advance: cannot load workflow chain config: ${err.message}`);
+      logError('Searched, in order:');
+      for (const p of chainsSearchPaths(deps.projectRoot)) logError(`  - ${p}`);
+      return 2;
+    }
+  }
+
+  const client = deps.client || createClient();
+  const ticketTypeFieldId = getTicketTypeFieldId(chains);
+  const projectKey = String(key).split('-')[0].toUpperCase();
+
+  try {
+    // ── Current state ────────────────────────────────────────────────
+    const { data: issueData } = await client.get(
+      `/rest/api/3/issue/${encodeURIComponent(key)}?fields=status,issuetype`
+    );
+    const currentStatus = issueData.fields?.status?.name;
+    const issueType = issueData.fields?.issuetype?.name;
+    if (!currentStatus || !issueType) {
+      logError(`jira advance: could not read status/issuetype for ${key}`);
+      return 2;
+    }
+
+    // ── Chain lookup ─────────────────────────────────────────────────
+    const chainConfig = getChainConfig(chains, projectKey, issueType);
+    const edges = getChainEdges(chains, projectKey, issueType);
+    if (!edges) {
+      const configured = listConfiguredIssueTypes(chains, projectKey);
+      logError(`jira advance: no workflow chain configured for project ${projectKey} issue type "${issueType}".`);
+      if (configured.length > 0) {
+        logError(`Configured issue types for ${projectKey}: ${configured.join(', ')}`);
+      } else {
+        logError(`No chains configured for project ${projectKey}.`);
+      }
+      logError('Add the chain to the shipped jira-workflow-chains.json (or an operator override), or use `jira transition` directly.');
+      return 2;
+    }
+
+    // ── Route (per mode) ─────────────────────────────────────────────
+    let target;
+    let path;
+
+    if (mode === 'next') {
+      let edge;
+      try {
+        edge = computeNextEdge(edges, currentStatus);
+      } catch (err) {
+        // More than one forward step - the operator has to choose.
+        logError(`jira advance --next: ${err.message}`);
+        return 1;
+      }
+      if (!edge) {
+        logError(`jira advance --next: "${currentStatus}" has no forward step in the ${projectKey} ${issueType} chain.`);
+        logError(`Chain statuses: ${chainStatuses(edges).join(' → ')}`);
+        logError('The status may be terminal, or off-chain (e.g. Product Backlog) - use `jira transition`.');
+        return 2;
+      }
+      target = edge.to;
+      path = [edge];
+    } else if (mode === 'close') {
+      target = resolveDoneStatus(edges, chainConfig);
+      if (!target) {
+        logError(`jira advance --close: cannot determine the Done status for the ${projectKey} ${issueType} chain.`);
+        logError(`Chain statuses: ${chainStatuses(edges).join(' → ')}`);
+        logError('Add a "doneStatus" to the issue type in jira-workflow-chains.json, or name the target status explicitly.');
+        return 2;
+      }
+      path = computePath(edges, currentStatus, target, { allowShortcuts: true });
+    } else {
+      try {
+        target = resolveTargetStatus(edges, targetInput);
+      } catch (err) {
+        logError(`jira advance: ${err.message}`);
+        return 1;
+      }
+      if (!target) {
+        logError(`jira advance: "${targetInput}" is not a status in the ${projectKey} ${issueType} chain.`);
+        logError(`Chain statuses: ${chainStatuses(edges).join(' → ')}`);
+        return 1;
+      }
+      // Shortcut-free first: a named target should be reached through the
+      // states the operator asked to pass through. Fall back to shortcuts
+      // only when there is no other way there.
+      path = computePath(edges, currentStatus, target);
+      if (path === null) {
+        path = computePath(edges, currentStatus, target, { allowShortcuts: true });
+      }
+    }
+
+    if (path === null) {
+      const reachable = reachableStatuses(edges, currentStatus);
+      logError(`jira advance: cannot reach "${target}" from "${currentStatus}" via the configured ${issueType} chain.`);
+      if (reachable.length > 0) {
+        logError(`Reachable from ${currentStatus}: ${reachable.join(', ')}`);
+      } else {
+        logError(`"${currentStatus}" has no forward edges in the chain (it may be off-chain, e.g. Product Backlog).`);
+        logError('Use `jira transition` to bring the issue back onto the chain.');
+      }
+      return 2;
+    }
+    if (path.length === 0) {
+      log(green(`${bold(key)} is already at ${currentStatus} - nothing to do.`));
+      return 0;
+    }
+
+    // ── Operator-consent guard ───────────────────────────────────────
+    // Some issue types' status is a judgement, not a consequence. The
+    // chain config says which, and why; refuse rather than infer. Placed
+    // after the no-op check so "already there" stays a harmless no-op.
+    const consent = getConsentPolicy(chainConfig);
+    if (consent.required && !hasConsent) {
+      logError(yellow(`jira advance: refusing to transition ${key} - ${issueType} transitions need explicit operator consent.`));
+      if (consent.reason) logError(`Why: ${consent.reason}`);
+      logError(`Refused plan: ${currentStatus} → ${target} (${path.length} step(s)).`);
+      logError('If - and only if - the operator has asked for this specific transition, re-run with --operator-consent.');
+      logError('Do not pass it because the children are done, the sprint closed, or the plan says so. Ask.');
+      return EXIT_CONSENT_REQUIRED;
+    }
+
+    // ── Gate analysis ────────────────────────────────────────────────
+    // Union of gate field kinds across the path.
+    const gateKinds = [];
+    for (const edge of path) {
+      for (const kind of edge.gate?.fields || []) {
+        if (!gateKinds.includes(kind)) gateKinds.push(kind);
+      }
+    }
+
+    // Fields supplied via flags (applied via update before walking).
+    const supplied = await buildRequiredFieldsPatch(args, client, textToAdf);
+    if (args['ticket-type']) {
+      supplied.fields[ticketTypeFieldId] = { value: String(args['ticket-type']) };
+      supplied.changed.push('ticket-type');
+    }
+
+    // For each gate kind: satisfied by a supplied flag, or by a value
+    // already on the issue. Only fetch issue field values when gates exist.
+    const missing = [];
+    if (gateKinds.length > 0) {
+      const fieldIdByKind = { ticketType: ticketTypeFieldId, originalEstimate: 'timetracking' };
+      if (gateKinds.includes('affectedServices')) {
+        fieldIdByKind.affectedServices = await discoverFieldId(client, 'Affected services');
+      }
+      const wanted = gateKinds.map((k) => fieldIdByKind[k]).filter(Boolean);
+      const { data: gateData } = await client.get(
+        `/rest/api/3/issue/${encodeURIComponent(key)}?fields=${wanted.join(',')}`
+      );
+      const existing = gateData.fields || {};
+
+      for (const kind of gateKinds) {
+        if (isGateSatisfiedByFlags(kind, supplied.fields, fieldIdByKind)) continue;
+        if (isGateSatisfiedOnIssue(kind, existing, fieldIdByKind)) continue;
+        missing.push(kind);
+      }
+    }
+
+    // ── Dry run ──────────────────────────────────────────────────────
+    if (dryRun) {
+      log(bold(`${key} (${issueType}): ${currentStatus} → ${target} - ${path.length} step(s)`) + dim(` [mode: ${mode}]`));
+      path.forEach((edge, i) => {
+        const notes = [];
+        if (edge.gate) notes.push(yellow('[gated: update-before-transition]'));
+        if (isShortcutEdge(edge)) {
+          const skips = (edge.skips || []).join(', ');
+          notes.push(yellow(`[shortcut${skips ? `: skips ${skips}` : ''}]`));
+        }
+        const suffix = notes.length > 0 ? `  ${notes.join(' ')}` : '';
+        log(`  ${i + 1}. ${edge.from} ${dim('--(')}${cyan(edge.transition)}${dim(')-->')} ${edge.to}${suffix}`);
+      });
+      if (supplied.changed.length > 0) {
+        log(`Fields to set via update first: ${supplied.changed.join(', ')}`);
+      }
+      if (missing.length > 0) {
+        logError(yellow('Gate fields missing - supply before this plan can execute:'));
+        for (const kind of missing) {
+          const info = GATE_FIELD_KINDS[kind] || { flag: kind, describe: kind };
+          logError(`  - ${bold(info.describe)}: ${info.flag}`);
+        }
+        return 1;
+      }
+      log(dim('Dry run - nothing executed.'));
+      return 0;
+    }
+
+    // ── Missing gate fields block execution ──────────────────────────
+    if (missing.length > 0) {
+      logError(yellow(`Cannot advance ${key}: gated step(s) on the path require fields that are neither set on the issue nor supplied:`));
+      for (const kind of missing) {
+        const info = GATE_FIELD_KINDS[kind] || { flag: kind, describe: kind };
+        logError(`  - ${bold(info.describe)}: ${info.flag}`);
+      }
+      logError('These fields cannot be set on the transition itself - advance applies them via update first.');
+      return 1;
+    }
+
+    // ── Apply supplied fields via update BEFORE transitioning ────────
+    if (Object.keys(supplied.fields).length > 0) {
+      await client.put(
+        `/rest/api/3/issue/${encodeURIComponent(key)}`,
+        { fields: supplied.fields }
+      );
+      log(`${bold(key)}: fields set via update - ${supplied.changed.join(', ')}`);
+    }
+
+    // ── Walk the chain ───────────────────────────────────────────────
+    for (const edge of path) {
+      const { data: transData } = await client.get(
+        `/rest/api/3/issue/${encodeURIComponent(key)}/transitions`
+      );
+      const transitions = transData.transitions || [];
+      const wanted = edge.transition.toLowerCase();
+      let match = transitions.find((t) => (t.name || '').toLowerCase() === wanted);
+      if (!match) {
+        match = transitions.find((t) => (t.name || '').toLowerCase().includes(wanted));
+      }
+      if (!match) {
+        logError(`jira advance: transition "${edge.transition}" not available from "${edge.from}" on ${key}.`);
+        logError('Available transitions:');
+        for (const t of transitions) {
+          logError(`  - ${t.name} (id: ${t.id})`);
+        }
+        logError('The chain config may be stale - update jira-workflow-chains.json.');
+        return 2;
+      }
+
+      await client.post(
+        `/rest/api/3/issue/${encodeURIComponent(key)}/transitions`,
+        { transition: { id: match.id } }
+      );
+
+      // Per-step verification: confirm we landed where the chain says.
+      const { data: verifyData } = await client.get(
+        `/rest/api/3/issue/${encodeURIComponent(key)}?fields=status`
+      );
+      const landed = verifyData.fields?.status?.name || 'Unknown';
+      if (landed.toLowerCase() !== edge.to.toLowerCase()) {
+        logError(`jira advance: after "${edge.transition}", ${key} landed on "${landed}" but the chain expected "${edge.to}".`);
+        logError('Stopping here. The chain config may be stale - update jira-workflow-chains.json.');
+        return 2;
+      }
+
+      log(green(`${bold(key)}: ${edge.from} → ${edge.to}`) + dim(` (via "${edge.transition}")`));
+    }
+
+    log(green(`${bold(key)} advanced to ${bold(target)} in ${path.length} step(s).`));
+    (deps.notifyWorkspace || notifyWorkspaceAsync)();
+    return 0;
+  } catch (err) {
+    if (err instanceof JiraError) {
+      const wrapped = maybeWrapRequiredFieldError(err);
+      logError(`jira advance: ${wrapped || err.message}`);
+      return err.exitCode;
+    }
+    throw err;
+  }
+}
+
+// ── Usage ────────────────────────────────────────────────────────────
+
+function logUsage(logError) {
+  logError('Usage: jira advance <KEY> <TARGET-STATUS> [--dry-run]');
+  logError('       jira advance <KEY> --next   [--dry-run]');
+  logError('       jira advance <KEY> --close  [--dry-run]');
+  logError('                    [--operator-consent] [--ticket-type V] [--affected-services NAME]');
+  logError('                    [--original-estimate DUR] [--field K=V] [--field-adf K=text]');
+}
+
+// ── Gate satisfaction checks ─────────────────────────────────────────
+
+function isGateSatisfiedByFlags(kind, suppliedFields, fieldIdByKind) {
+  switch (kind) {
+    case 'ticketType':
+      return fieldIdByKind.ticketType in suppliedFields;
+    case 'affectedServices':
+      return fieldIdByKind.affectedServices in suppliedFields;
+    case 'originalEstimate':
+      return Boolean(suppliedFields.timetracking?.originalEstimate);
+    default:
+      // Unknown gate kind: treat generic --field coverage as unknowable;
+      // require it explicitly so the operator sees the gap.
+      return false;
+  }
+}
+
+function isGateSatisfiedOnIssue(kind, existingFields, fieldIdByKind) {
+  switch (kind) {
+    case 'ticketType': {
+      const v = existingFields[fieldIdByKind.ticketType];
+      return v !== null && v !== undefined;
+    }
+    case 'affectedServices': {
+      const v = existingFields[fieldIdByKind.affectedServices];
+      return Array.isArray(v) ? v.length > 0 : Boolean(v);
+    }
+    case 'originalEstimate':
+      return Boolean(existingFields.timetracking?.originalEstimate);
+    default:
+      return false;
+  }
+}

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

@@ -0,0 +1,129 @@
+// attach.mjs - Attach one or more files to an existing Jira issue.
+//
+// Usage:
+//   jira attach <KEY> -f <FILE> [-f <FILE>...]
+//
+// Posts each file to /rest/api/3/issue/{KEY}/attachments. Honours the
+// Atlassian CSRF bypass (X-Atlassian-Token: no-check) - handled inside
+// client.postFile.
+
+import { readFile, stat } from 'node:fs/promises';
+import { basename, extname } from 'node:path';
+
+import { createClient, JiraError } from '../client.mjs';
+import { bold, green } from '../format.mjs';
+import { asList } from '../metadata.mjs';
+import { notifyWorkspaceAsync } from '../invalidate.mjs';
+
+const HELP = `jira attach - Attach files to an issue
+
+Usage:
+  jira attach <KEY> -f <FILE> [-f <FILE>...]
+
+Arguments:
+  KEY             Issue key (e.g. AI-1552)
+
+Options:
+  -f, --file FILE Path to a file to attach. Repeatable for multiple files.
+
+Examples:
+  jira attach AI-1552 -f ./plan-1.md
+  jira attach AI-1552 -f ./plan-1.md -f ./plan-2.md
+`;
+
+const MIME_BY_EXT = {
+  '.md': 'text/markdown',
+  '.txt': 'text/plain',
+  '.json': 'application/json',
+  '.yaml': 'application/yaml',
+  '.yml': 'application/yaml',
+  '.html': 'text/html',
+  '.csv': 'text/csv',
+  '.pdf': 'application/pdf',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml',
+  '.log': 'text/plain',
+};
+
+function guessMime(filePath) {
+  const ext = extname(filePath).toLowerCase();
+  return MIME_BY_EXT[ext] || 'application/octet-stream';
+}
+
+/**
+ * Run the attach command.
+ *
+ * @param {string[]} argv  Args after 'attach'
+ * @param {object} [deps]  Dependency overrides
+ * @returns {Promise<number>}
+ */
+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 attach <KEY> -f <FILE> [-f <FILE>...]');
+    return 1;
+  }
+
+  const fileArgs = asList(args.file ?? args.f);
+  if (fileArgs.length === 0) {
+    logError('jira attach: at least one -f FILE is required');
+    return 1;
+  }
+
+  const client = deps.client || createClient();
+
+  try {
+    for (const filePath of fileArgs) {
+      try {
+        const st = await stat(filePath);
+        if (!st.isFile()) {
+          throw new JiraError(`Not a regular file: ${filePath}`, 1);
+        }
+      } catch (err) {
+        if (err instanceof JiraError) throw err;
+        throw new JiraError(`Cannot read file "${filePath}": ${err.message}`, 1);
+      }
+    }
+
+    for (const filePath of fileArgs) {
+      const buffer = await readFile(filePath);
+      const filename = basename(filePath);
+      const mime = guessMime(filePath);
+      const { data } = await client.postFile(
+        `/rest/api/3/issue/${encodeURIComponent(key)}/attachments`,
+        buffer,
+        filename,
+        mime,
+      );
+      // Jira returns an array of attachment metadata on success.
+      const attached = Array.isArray(data) && data[0] ? data[0] : null;
+      const id = attached?.id ?? '(unknown id)';
+      const size = attached?.size ?? buffer.length;
+      log(green(`Attached: ${bold(filename)}`) + `  (id=${id}, ${size} bytes)`);
+    }
+
+    const creds = client.getCredentials();
+    log(`  URL: https://${creds.domain}.atlassian.net/browse/${key}`);
+    (deps.notifyWorkspace || notifyWorkspaceAsync)();
+    return 0;
+  } catch (err) {
+    if (err instanceof JiraError) {
+      logError(`jira attach: ${err.message}`);
+      return err.exitCode;
+    }
+    throw err;
+  }
+}

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

@@ -0,0 +1,53 @@
+// auth.mjs - Verify Jira credentials.
+//
+// Calls GET /rest/api/3/myself and prints the current user's details.
+// Exit 0 on success, 2 on auth failure.
+
+import { createClient, JiraError } from '../client.mjs';
+import { bold, green, red } from '../format.mjs';
+
+const HELP = `jira auth - Verify Jira credentials
+
+Usage:
+  jira auth
+
+Checks the configured Jira credentials by fetching the current user's profile.
+Prints display name, email, account ID, and timezone.
+`;
+
+/**
+ * Run the auth command.
+ *
+ * @param {string[]} argv  Remaining args after 'auth'
+ * @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;
+  }
+
+  const client = deps.client || createClient();
+
+  try {
+    const { data } = await client.get('/rest/api/3/myself');
+
+    log(green('Authentication successful.\n'));
+    log(`  ${bold('Name:')}       ${data.displayName || 'N/A'}`);
+    log(`  ${bold('Email:')}      ${data.emailAddress || 'N/A'}`);
+    log(`  ${bold('Account ID:')} ${data.accountId || 'N/A'}`);
+    log(`  ${bold('Timezone:')}   ${data.timeZone || 'N/A'}`);
+
+    return 0;
+  } catch (err) {
+    if (err instanceof JiraError) {
+      logError(red(`Authentication failed: ${err.message}`));
+      return err.exitCode;
+    }
+    throw err;
+  }
+}