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

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

@@ -0,0 +1,380 @@
+// worklog.mjs - Log or list worklogs on a Jira issue.
+//
+// Usage:
+//   jira worklog <KEY> --time <dur>              e.g. --time 2d4h30m
+//   jira worklog <KEY> --from <iso> [--to <iso>] elapsed = to (default now) - from
+//   jira worklog <KEY> --time <dur> --comment "..."
+//   jira worklog <KEY> --list                     recent worklogs for the issue
+//   jira worklog <KEY> --time 1h --dry-run        print the request, send nothing
+//
+// Time semantics:
+//   Logged time represents REAL wall-clock elapsed time - agent time, human
+//   time, overnight sleep time all included. `--from/--to` is the primary
+//   ergonomic path; record ticket-start time, log the true delta at close.
+//
+//   Duration format is Jira-style tokens: "1d 4h 30m" or "1d4h30m". `d`
+//   means a literal 24-hour day (NOT Jira's 8-hour workday). The command
+//   converts everything to seconds and posts `timeSpentSeconds` so Jira's
+//   workday interpretation cannot silently rescale the number.
+//
+// Exit codes:
+//   0 - success
+//   1 - usage error (bad args, unparseable duration, from > to)
+//   2 - API error (issue not found, permission denied)
+
+import { createClient, JiraError } from '../client.mjs';
+import { textToAdf, adfToText } from '../adf.mjs';
+import { bold, dim, green } from '../format.mjs';
+import { notifyWorkspaceAsync } from '../invalidate.mjs';
+
+const HELP = `jira worklog - Log or list worklogs on a Jira issue
+
+Usage:
+  jira worklog <KEY> --time <dur>                  Log elapsed time
+  jira worklog <KEY> --from <iso> [--to <iso>]     Log delta between two timestamps
+  jira worklog <KEY> --time <dur> --comment "..."  Log time with a comment
+  jira worklog <KEY> --list                        Show recent worklogs
+
+Options:
+  --time DUR         Duration to log. Jira-style tokens "1d 4h 30m" or
+                     compact "1d4h30m". "d" = 24-hour wall day (NOT Jira's
+                     8h workday). Rounds to the nearest minute.
+  --from ISO         Start timestamp (ISO-8601). Elapsed is computed as
+                     --to (default: now) minus --from, rounded to the
+                     nearest minute. Mutually exclusive with --time.
+  --to ISO           End timestamp (ISO-8601). Defaults to now.
+  --comment TEXT     Optional worklog comment (plain text, converted to ADF).
+  --started ISO      Timestamp recorded as the worklog start. Defaults to
+                     the derived --from, else (now - elapsed).
+  --list             Show the 10 most recent worklogs on the issue.
+  --dry-run          Print the request path + body, send nothing (exit 0).
+  --help, -h         Show this help.
+
+Duration semantics:
+  All input is converted to seconds and posted as timeSpentSeconds, so
+  1d always means 86400 seconds regardless of the project's time-tracking
+  workday setting.
+
+Examples:
+  jira worklog AI-1810 --time 2h30m
+  jira worklog AI-1810 --from 2026-08-21T09:00:00Z
+  jira worklog AI-1810 --from 2026-08-20T14:00:00Z --to 2026-08-21T09:15:00Z
+  jira worklog AI-1810 --time 45m --comment "Investigation + write-up"
+  jira worklog AI-1810 --list
+`;
+
+// ── Duration parsing ─────────────────────────────────────────────────
+
+const SECONDS_PER = {
+  d: 24 * 60 * 60,   // 24-hour wall day (documented; NOT the Jira 8h workday)
+  h: 60 * 60,
+  m: 60,
+};
+
+/**
+ * Parse a Jira-style duration into seconds.
+ *
+ * Accepts space-separated or compact forms, mixed order, case-insensitive:
+ *   "1d 4h 30m", "1d4h30m", "30m", "2H", "1d 30m".
+ *
+ * Each unit (`d`, `h`, `m`) may appear at most once. Returns an integer
+ * number of seconds. Throws JiraError(1) on any parse failure so the caller
+ * exits with a usage-error code.
+ *
+ * @param {string} raw  Duration string as supplied by the operator
+ * @returns {number}    Total seconds
+ */
+export function parseDuration(raw) {
+  if (raw == null || typeof raw !== 'string' || raw.trim() === '') {
+    throw new JiraError('Duration is empty; expected e.g. "1d 4h 30m"', 1);
+  }
+  const compact = raw.trim().replace(/\s+/g, '').toLowerCase();
+  // Must be one or more <int><unit> tokens, nothing else.
+  if (!/^(?:\d+[dhm])+$/.test(compact)) {
+    throw new JiraError(
+      `Unparseable duration "${raw}"; expected tokens like "1d 4h 30m"`,
+      1
+    );
+  }
+  const seen = new Set();
+  let total = 0;
+  const tokenRe = /(\d+)([dhm])/g;
+  let m;
+  while ((m = tokenRe.exec(compact)) !== null) {
+    const [, nStr, unit] = m;
+    if (seen.has(unit)) {
+      throw new JiraError(
+        `Duration "${raw}" repeats unit "${unit}"; use one of each`,
+        1
+      );
+    }
+    seen.add(unit);
+    const n = Number.parseInt(nStr, 10);
+    if (!Number.isFinite(n) || n < 0) {
+      throw new JiraError(`Duration "${raw}" has invalid number "${nStr}"`, 1);
+    }
+    total += n * SECONDS_PER[unit];
+  }
+  if (total === 0) {
+    throw new JiraError(`Duration "${raw}" evaluates to zero seconds`, 1);
+  }
+  return total;
+}
+
+/**
+ * Format a duration (seconds) back into a compact "1d 4h 30m" string
+ * for human display. Zero-value units are dropped.
+ *
+ * @param {number} seconds
+ * @returns {string}
+ */
+export function formatDuration(seconds) {
+  let s = Math.max(0, Math.round(seconds));
+  const d = Math.floor(s / SECONDS_PER.d); s -= d * SECONDS_PER.d;
+  const h = Math.floor(s / SECONDS_PER.h); s -= h * SECONDS_PER.h;
+  const m = Math.floor(s / SECONDS_PER.m); s -= m * SECONDS_PER.m;
+  const parts = [];
+  if (d) parts.push(`${d}d`);
+  if (h) parts.push(`${h}h`);
+  if (m) parts.push(`${m}m`);
+  if (s) parts.push(`${s}s`);
+  return parts.length > 0 ? parts.join(' ') : '0m';
+}
+
+// ── Timestamp handling ───────────────────────────────────────────────
+
+/**
+ * Parse an ISO-8601 timestamp; throws JiraError(1) if invalid.
+ *
+ * @param {string} iso    ISO-8601 timestamp
+ * @param {string} label  Flag name for the error message ("--from"/"--to")
+ * @returns {Date}
+ */
+export function parseIsoTimestamp(iso, label) {
+  if (iso == null || typeof iso !== 'string' || iso.trim() === '') {
+    throw new JiraError(`${label} is empty; expected an ISO-8601 timestamp`, 1);
+  }
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) {
+    throw new JiraError(`${label} "${iso}" is not a valid ISO-8601 timestamp`, 1);
+  }
+  return d;
+}
+
+/**
+ * Format a Date for Jira's `started` worklog field, which requires the
+ * `yyyy-MM-dd'T'HH:mm:ss.SSSZ` shape with a numeric timezone offset (no colon).
+ *
+ * JS `toISOString()` produces `...Z`; Jira rejects that and wants `+0000`.
+ *
+ * @param {Date} d
+ * @returns {string}
+ */
+export function formatJiraStarted(d) {
+  return d.toISOString().replace(/Z$/, '+0000');
+}
+
+// ── Arg parsing ──────────────────────────────────────────────────────
+
+/**
+ * Parse argv for the worklog command.
+ *
+ * @param {string[]} argv  Args after 'worklog'
+ * @returns {object}
+ */
+function parseWorklogArgs(argv) {
+  const out = {
+    key: null,
+    time: null,
+    from: null,
+    to: null,
+    comment: null,
+    started: null,
+    list: false,
+    dryRun: false,
+    help: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') { out.help = true; continue; }
+    if (a === '--list') { out.list = true; continue; }
+    if (a === '--dry-run') { out.dryRun = true; continue; }
+    if (a === '--time') { out.time = argv[++i]; continue; }
+    if (a === '--from') { out.from = argv[++i]; continue; }
+    if (a === '--to') { out.to = argv[++i]; continue; }
+    if (a === '--comment') { out.comment = argv[++i]; continue; }
+    if (a === '--started') { out.started = argv[++i]; continue; }
+    if (a.startsWith('-')) {
+      throw new JiraError(`Unknown flag "${a}"`, 1);
+    }
+    if (!out.key) { out.key = a; continue; }
+    throw new JiraError(`Unexpected positional argument "${a}"`, 1);
+  }
+  return out;
+}
+
+// ── Runner ───────────────────────────────────────────────────────────
+
+/**
+ * Run the worklog command.
+ *
+ * @param {string[]} argv  Args after 'worklog'
+ * @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;
+
+  let parsed;
+  try {
+    parsed = parseWorklogArgs(argv);
+  } catch (err) {
+    if (err instanceof JiraError) {
+      logError(`jira worklog: ${err.message}`);
+      return err.exitCode;
+    }
+    throw err;
+  }
+
+  if (parsed.help) { log(HELP); return 0; }
+
+  if (!parsed.key) {
+    logError('Usage: jira worklog <KEY> --time <dur>');
+    logError('       jira worklog <KEY> --from <iso> [--to <iso>]');
+    logError('       jira worklog <KEY> --list');
+    return 1;
+  }
+
+  const client = deps.client || createClient();
+
+  if (parsed.list) {
+    return listWorklogs(client, parsed.key, log, logError);
+  }
+
+  // ── Decide elapsed seconds and started timestamp ──────────────────
+  let elapsedSeconds;
+  let derivedStarted = null;
+
+  const hasTime = parsed.time != null;
+  const hasFrom = parsed.from != null;
+
+  if (hasTime && hasFrom) {
+    logError('jira worklog: --time and --from are mutually exclusive');
+    return 1;
+  }
+  if (!hasTime && !hasFrom) {
+    logError('jira worklog: provide --time <dur> or --from <iso> (or --list)');
+    return 1;
+  }
+
+  try {
+    if (hasTime) {
+      elapsedSeconds = parseDuration(String(parsed.time));
+    } else {
+      const fromDate = parseIsoTimestamp(String(parsed.from), '--from');
+      const toDate = parsed.to != null
+        ? parseIsoTimestamp(String(parsed.to), '--to')
+        : new Date();
+      const deltaMs = toDate.getTime() - fromDate.getTime();
+      if (deltaMs <= 0) {
+        logError('jira worklog: --from must be earlier than --to');
+        return 1;
+      }
+      // Round to the nearest minute per the ergonomic contract.
+      elapsedSeconds = Math.round(deltaMs / 1000 / 60) * 60;
+      if (elapsedSeconds < 60) {
+        // Sub-minute delta after rounding is not useful and Jira rejects
+        // zero-second worklogs anyway.
+        logError(
+          `jira worklog: elapsed time (${Math.round(deltaMs / 1000)}s) rounds ` +
+          'to under a minute; nothing to log'
+        );
+        return 1;
+      }
+      derivedStarted = fromDate;
+    }
+
+    // Started: explicit --started wins; else derived from --from; else
+    // (now - elapsed).
+    let startedDate;
+    if (parsed.started != null) {
+      startedDate = parseIsoTimestamp(String(parsed.started), '--started');
+    } else if (derivedStarted) {
+      startedDate = derivedStarted;
+    } else {
+      startedDate = new Date(Date.now() - elapsedSeconds * 1000);
+    }
+
+    // ── Build request body ─────────────────────────────────────────
+    const body = {
+      timeSpentSeconds: elapsedSeconds,
+      started: formatJiraStarted(startedDate),
+    };
+    if (parsed.comment) {
+      body.comment = textToAdf(String(parsed.comment));
+    }
+
+    const path = `/rest/api/3/issue/${encodeURIComponent(parsed.key)}/worklog`;
+
+    if (parsed.dryRun) {
+      log(dim('DRY RUN - no request sent'));
+      log(`POST ${path}`);
+      log(JSON.stringify(body, null, 2));
+      log(dim(`(elapsed: ${formatDuration(elapsedSeconds)})`));
+      return 0;
+    }
+
+    const { data } = await client.post(path, body);
+    log(green(`Worklog added to ${bold(parsed.key)}.`)
+      + dim(` (id: ${data && data.id}, ${formatDuration(elapsedSeconds)})`));
+
+    (deps.notifyWorkspace || notifyWorkspaceAsync)();
+    return 0;
+  } catch (err) {
+    if (err instanceof JiraError) {
+      logError(`jira worklog: ${err.message}`);
+      return err.exitCode;
+    }
+    throw err;
+  }
+}
+
+/**
+ * List the 10 most recent worklogs on an issue (newest last - matches the
+ * REST endpoint's natural order).
+ */
+async function listWorklogs(client, key, log, logError) {
+  try {
+    const { data } = await client.get(
+      `/rest/api/3/issue/${encodeURIComponent(key)}/worklog?maxResults=10`
+    );
+
+    const worklogs = data.worklogs || [];
+    if (worklogs.length === 0) {
+      log(dim(`No worklogs on ${key}.`));
+      return 0;
+    }
+
+    log(bold(`Worklogs on ${key}`) + dim(` (${worklogs.length} shown)\n`));
+    for (const w of worklogs) {
+      const who = (w.author && (w.author.displayName || w.author.emailAddress))
+        || 'unknown';
+      const started = w.started || '';
+      const timeStr = formatDuration(w.timeSpentSeconds ?? 0);
+      log(`${bold(timeStr.padEnd(10))} ${who}  ${dim(started)}`);
+      if (w.comment) {
+        const bodyText = adfToText(w.comment);
+        if (bodyText) log(`  ${bodyText.split('\n').join('\n  ')}`);
+      }
+      log('');
+    }
+    return 0;
+  } catch (err) {
+    if (err instanceof JiraError) {
+      logError(`jira worklog: Failed to list worklogs on ${key}: ${err.message}`);
+      return err.exitCode;
+    }
+    throw err;
+  }
+}

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

@@ -0,0 +1,267 @@
+// format.mjs - Terminal output formatting for Jira data.
+//
+// Provides table rendering, issue/project/comment formatting, and
+// ANSI color helpers. Used by CLI commands and workspace API handlers.
+//
+// Zero external dependencies.
+
+// ── ANSI color helpers ───────────────────────────────────────────────
+
+const IS_TTY = process.stdout.isTTY;
+
+function ansi(code, text) {
+  if (!IS_TTY) return text;
+  return `\x1b[${code}m${text}\x1b[0m`;
+}
+
+export function bold(text) { return ansi('1', text); }
+export function dim(text) { return ansi('2', text); }
+export function red(text) { return ansi('31', text); }
+export function green(text) { return ansi('32', text); }
+export function yellow(text) { return ansi('33', text); }
+export function blue(text) { return ansi('34', text); }
+export function cyan(text) { return ansi('36', text); }
+
+// ── Status color mapping ─────────────────────────────────────────────
+
+const STATUS_COLORS = {
+  'done': green,
+  'closed': green,
+  'resolved': green,
+  'in progress': blue,
+  'in review': cyan,
+  'to do': yellow,
+  'open': yellow,
+  'backlog': dim,
+};
+
+function colorStatus(status) {
+  if (!status) return '';
+  const lower = status.toLowerCase();
+  const colorFn = STATUS_COLORS[lower] || ((s) => s);
+  return colorFn(status);
+}
+
+// ── Priority rendering ───────────────────────────────────────────────
+
+const PRIORITY_LABELS = {
+  1: 'Highest',
+  2: 'High',
+  3: 'Medium',
+  4: 'Low',
+  5: 'Lowest',
+};
+
+function formatPriority(priority) {
+  if (!priority) return '';
+  const id = priority.id ? parseInt(priority.id, 10) : null;
+  return priority.name || PRIORITY_LABELS[id] || '';
+}
+
+// ── Table formatting ─────────────────────────────────────────────────
+
+/**
+ * Render rows as an aligned text table.
+ *
+ * @param {Array<object>} rows       Array of data objects
+ * @param {Array<object>} columns    Column definitions: { key, label, width?, align? }
+ *   - key: property name on each row
+ *   - label: column header text
+ *   - width: max column width (optional, auto-calculated if omitted)
+ *   - align: 'left' (default) or 'right'
+ * @returns {string} Formatted table
+ */
+export function formatTable(rows, columns) {
+  if (!rows || rows.length === 0) return '';
+
+  // Calculate column widths
+  const colWidths = columns.map((col) => {
+    const headerLen = col.label.length;
+    const maxDataLen = rows.reduce((max, row) => {
+      const val = String(row[col.key] ?? '');
+      return Math.max(max, val.length);
+    }, 0);
+    const natural = Math.max(headerLen, maxDataLen);
+    return col.width ? Math.min(natural, col.width) : natural;
+  });
+
+  // Header
+  const header = columns.map((col, i) => {
+    return pad(col.label, colWidths[i], col.align || 'left');
+  }).join('  ');
+
+  // Separator
+  const sep = colWidths.map((w) => '-'.repeat(w)).join('  ');
+
+  // Rows
+  const body = rows.map((row) => {
+    return columns.map((col, i) => {
+      const val = String(row[col.key] ?? '');
+      const truncated = val.length > colWidths[i]
+        ? val.slice(0, colWidths[i] - 1) + '\u2026'
+        : val;
+      return pad(truncated, colWidths[i], col.align || 'left');
+    }).join('  ');
+  });
+
+  return [bold(header), sep, ...body].join('\n');
+}
+
+function pad(str, width, align) {
+  if (align === 'right') return str.padStart(width);
+  return str.padEnd(width);
+}
+
+// ── Issue formatting ─────────────────────────────────────────────────
+
+/**
+ * Format a single Jira issue for terminal display.
+ *
+ * @param {object} issue   Jira issue object (from API response)
+ * @returns {string}       Formatted output
+ */
+export function formatIssue(issue) {
+  if (!issue) return '';
+
+  const f = issue.fields || {};
+  const lines = [];
+
+  // Key + Summary
+  lines.push(`${bold(issue.key)}  ${f.summary || '(no summary)'}`);
+  lines.push('');
+
+  // Status + Priority
+  const status = f.status?.name || 'Unknown';
+  const priority = formatPriority(f.priority);
+  const type = f.issuetype?.name || '';
+  const metaParts = [colorStatus(status)];
+  if (priority) metaParts.push(priority);
+  if (type) metaParts.push(type);
+  lines.push(metaParts.join('  |  '));
+
+  // Assignee + Reporter
+  const assignee = f.assignee?.displayName || dim('Unassigned');
+  const reporter = f.reporter?.displayName || '';
+  lines.push(`Assignee: ${assignee}`);
+  if (reporter) lines.push(`Reporter: ${reporter}`);
+
+  // Labels
+  if (f.labels && f.labels.length > 0) {
+    lines.push(`Labels: ${f.labels.join(', ')}`);
+  }
+
+  // Sprint
+  if (f.sprint) {
+    lines.push(`Sprint: ${f.sprint.name || f.sprint.id}`);
+  }
+
+  // Created / Updated
+  if (f.created) lines.push(`Created: ${formatDate(f.created)}`);
+  if (f.updated) lines.push(`Updated: ${formatDate(f.updated)}`);
+
+  // Description excerpt
+  if (f.description) {
+    lines.push('');
+    lines.push(dim('--- Description ---'));
+    // Import adf lazily to avoid circular deps - but in practice
+    // format.mjs will be used alongside adf.mjs at the call site.
+    // Here we just show the raw type hint.
+    lines.push(dim('(ADF document - use adfToText/adfToMarkdown to render)'));
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format a list of issues as a compact table.
+ *
+ * @param {Array<object>} issues  Array of Jira issues
+ * @returns {string}              Formatted table
+ */
+export function formatIssueList(issues) {
+  if (!issues || issues.length === 0) return dim('No issues found.');
+
+  const rows = issues.map((issue) => {
+    const f = issue.fields || {};
+    return {
+      key: issue.key,
+      type: f.issuetype?.name || '',
+      status: f.status?.name || '',
+      priority: formatPriority(f.priority),
+      assignee: f.assignee?.displayName || '',
+      summary: f.summary || '',
+    };
+  });
+
+  return formatTable(rows, [
+    { key: 'key', label: 'Key', width: 12 },
+    { key: 'type', label: 'Type', width: 10 },
+    { key: 'status', label: 'Status', width: 14 },
+    { key: 'priority', label: 'Pri', width: 8 },
+    { key: 'assignee', label: 'Assignee', width: 20 },
+    { key: 'summary', label: 'Summary', width: 50 },
+  ]);
+}
+
+// ── Project formatting ───────────────────────────────────────────────
+
+/**
+ * Format a single Jira project for terminal display.
+ *
+ * @param {object} project  Jira project object
+ * @returns {string}        Formatted output
+ */
+export function formatProject(project) {
+  if (!project) return '';
+
+  const lines = [];
+  lines.push(`${bold(project.key)}  ${project.name || ''}`);
+  if (project.projectTypeKey) lines.push(`Type: ${project.projectTypeKey}`);
+  if (project.lead?.displayName) lines.push(`Lead: ${project.lead.displayName}`);
+  if (project.description) lines.push(`\n${project.description}`);
+
+  return lines.join('\n');
+}
+
+// ── Comment formatting ───────────────────────────────────────────────
+
+/**
+ * Format a single Jira comment for terminal display.
+ *
+ * @param {object} comment  Jira comment object
+ * @returns {string}        Formatted output
+ */
+export function formatComment(comment) {
+  if (!comment) return '';
+
+  const author = comment.author?.displayName || 'Unknown';
+  const created = comment.created ? formatDate(comment.created) : '';
+  const updated = comment.updated ? formatDate(comment.updated) : '';
+
+  const lines = [];
+  lines.push(`${bold(author)}  ${dim(created)}`);
+  if (updated && updated !== created) {
+    lines.push(dim(`(edited ${updated})`));
+  }
+
+  // Comment body is ADF - note that like formatIssue, the caller should
+  // render ADF before passing to this function for the body display.
+  if (comment.body) {
+    lines.push('');
+    lines.push(dim('(ADF body - use adfToText/adfToMarkdown to render)'));
+  }
+
+  return lines.join('\n');
+}
+
+// ── Date formatting ──────────────────────────────────────────────────
+
+function formatDate(isoString) {
+  if (!isoString) return '';
+  try {
+    const d = new Date(isoString);
+    return d.toISOString().slice(0, 10);
+  } catch {
+    return isoString;
+  }
+}