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

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

@@ -0,0 +1,142 @@
+// test.mjs - Live API contract smoke test.
+//
+// Hits key Jira endpoints and validates response shapes. NO MUTATIONS.
+// Used to verify the API still behaves as expected after upgrades,
+// config changes, or permission adjustments.
+//
+// Exit 0 if all pass, 2 if any fail.
+
+import { createClient, JiraError } from '../client.mjs';
+import { bold, dim, green, red, yellow } from '../format.mjs';
+
+const HELP = `jira test - Live API contract smoke test
+
+Usage:
+  jira test
+
+Runs read-only checks against the Jira API to validate response shapes
+and connectivity. No data is created, modified, or deleted.
+
+Options:
+  --help, -h  Show this help
+`;
+
+/**
+ * Run the test command.
+ *
+ * @param {string[]} argv  Remaining args after 'test'
+ * @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();
+
+  log(bold('Jira API Contract Tests\n'));
+
+  const results = [];
+
+  // ── Test 1: Auth check ───────────────────────────────────────────
+  results.push(await runTest(log, 'Auth (GET /rest/api/3/myself)', async () => {
+    const { data } = await client.get('/rest/api/3/myself');
+    assert(data.accountId, 'missing accountId');
+    assert(data.displayName, 'missing displayName');
+    return `user: ${data.displayName}`;
+  }));
+
+  // ── Test 2: Projects ─────────────────────────────────────────────
+  results.push(await runTest(log, 'Projects (GET /rest/api/3/project/search)', async () => {
+    const { data } = await client.get('/rest/api/3/project/search?maxResults=1');
+    assert(Array.isArray(data.values), 'values is not an array');
+    return `${data.total ?? data.values.length} projects`;
+  }));
+
+  // ── Test 3: JQL Search ───────────────────────────────────────────
+  let searchIssueKey = null;
+  results.push(await runTest(log, 'Search (POST /rest/api/3/search/jql)', async () => {
+    const { data } = await client.post('/rest/api/3/search/jql', {
+      jql: 'project = AI ORDER BY updated DESC',
+      fields: ['summary'],
+      maxResults: 1,
+    });
+    assert(Array.isArray(data.issues), 'issues is not an array');
+    if (data.issues.length > 0) {
+      searchIssueKey = data.issues[0].key;
+    }
+    return `${data.issues.length} issue(s) returned${searchIssueKey ? `, first: ${searchIssueKey}` : ''}`;
+  }));
+
+  // ── Test 4: Issue fetch ──────────────────────────────────────────
+  results.push(await runTest(log, 'Issue fetch (GET /rest/api/3/issue/{key})', async () => {
+    if (!searchIssueKey) {
+      return 'SKIP: no issue from search to fetch';
+    }
+    const { data } = await client.get(
+      `/rest/api/3/issue/${searchIssueKey}?fields=summary,status`
+    );
+    assert(data.fields?.summary, 'missing fields.summary');
+    return `${data.key}: ${data.fields.summary}`;
+  }));
+
+  // ── Test 5: Boards ──────────────────────────────────────────────
+  results.push(await runTest(log, 'Boards (GET /rest/agile/1.0/board)', async () => {
+    const { data } = await client.get('/rest/agile/1.0/board?maxResults=1');
+    assert(Array.isArray(data.values), 'values is not an array');
+    return `${data.total ?? data.values.length} board(s)`;
+  }));
+
+  // ── Summary ──────────────────────────────────────────────────────
+  const passed = results.filter((r) => r.passed).length;
+  const total = results.length;
+  const skipped = results.filter((r) => r.skipped).length;
+
+  log('');
+  const color = passed === total ? green : (passed >= total - 1 ? yellow : red);
+  log(color(bold(`${passed}/${total} passed`)) + (skipped ? dim(` (${skipped} skipped)`) : ''));
+
+  return passed === total ? 0 : 2;
+}
+
+/**
+ * Run a single test and print result.
+ *
+ * @param {Function} log       Output function
+ * @param {string} name        Test name
+ * @param {Function} testFn    Async function to execute
+ * @returns {Promise<{ passed: boolean, skipped: boolean }>}
+ */
+async function runTest(log, name, testFn) {
+  const start = Date.now();
+  try {
+    const detail = await testFn();
+    const ms = Date.now() - start;
+    const skipped = typeof detail === 'string' && detail.startsWith('SKIP:');
+    if (skipped) {
+      log(`  ${yellow('SKIP')}  ${name}  ${dim(`${ms}ms`)}  ${dim(detail.slice(6))}`);
+      return { passed: true, skipped: true };
+    }
+    log(`  ${green('PASS')}  ${name}  ${dim(`${ms}ms`)}  ${dim(detail || '')}`);
+    return { passed: true, skipped: false };
+  } catch (err) {
+    const ms = Date.now() - start;
+    const msg = err instanceof JiraError ? err.message : (err.message || String(err));
+    log(`  ${red('FAIL')}  ${name}  ${dim(`${ms}ms`)}  ${red(msg)}`);
+    return { passed: false, skipped: false };
+  }
+}
+
+/**
+ * Simple assertion helper - throws on falsy value.
+ */
+function assert(value, message) {
+  if (!value) {
+    throw new Error(`Assertion failed: ${message}`);
+  }
+}

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

@@ -0,0 +1,197 @@
+// transition.mjs - Change Jira issue status via transitions.
+//
+// Fetches available transitions, fuzzy-matches the target status,
+// checks for required fields, and executes the transition. Fields can
+// be set on the transition payload itself (per Atlassian docs) - useful
+// when a transition gate requires a customfield to be populated.
+
+import { createClient, JiraError } from '../client.mjs';
+import { textToAdf } from '../adf.mjs';
+import { bold, green, yellow, dim } from '../format.mjs';
+import {
+  buildRequiredFieldsPatch,
+  maybeWrapRequiredFieldError,
+} from '../required-fields.mjs';
+import { notifyWorkspaceAsync } from '../invalidate.mjs';
+
+const HELP = `jira transition - Change issue status
+
+Usage:
+  jira transition <KEY> <STATUS>
+                  [--field K=V] [--field-adf K=text]
+                  [--affected-services NAME] [--original-estimate DURATION]
+
+Arguments:
+  KEY            Issue key (e.g. AI-123)
+  STATUS         Target status name (case-insensitive, partial match)
+
+Options:
+  --field K=V               Set an arbitrary field on the transition payload
+                            (repeatable). V is JSON-parsed if it looks like
+                            JSON, otherwise treated as a string.
+  --field-adf K=text        Set an ADF-typed field; text is converted to ADF.
+                            (Repeatable.)
+  --affected-services NAME  Set Affected services on the transition payload
+                            (resolved to ARI via service-registry).
+  --original-estimate DUR   Set timetracking.originalEstimate on the
+                            transition payload (Jira duration syntax).
+
+Discovers available transitions for the issue, fuzzy-matches the target
+status, and executes the transition. If the transition declares required
+fields and you haven't supplied them via the flags above, the CLI surfaces
+the gap and exits without proceeding.
+
+Examples:
+  jira transition AI-123 "In Progress"
+  jira transition AI-123 done
+  jira transition AI-1556 review --original-estimate 8h \\
+                  --affected-services "Artificial Intelligence Services"
+`;
+
+/**
+ * Run the transition command.
+ *
+ * @param {string[]} argv  Remaining args after '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 key = args._[0];
+  const targetStatus = args._.slice(1).join(' ');
+
+  if (!key || !targetStatus) {
+    logError('Usage: jira transition <KEY> <STATUS> [--field K=V] [--field-adf K=text]');
+    logError('                                       [--affected-services NAME] [--original-estimate DUR]');
+    return 1;
+  }
+
+  const client = deps.client || createClient();
+
+  try {
+    // Get current issue status for display
+    const { data: issueData } = await client.get(
+      `/rest/api/3/issue/${encodeURIComponent(key)}?fields=status`
+    );
+    const currentStatus = issueData.fields?.status?.name || 'Unknown';
+
+    // Discover available transitions
+    const { data: transData } = await client.get(
+      `/rest/api/3/issue/${encodeURIComponent(key)}/transitions?expand=transitions.fields`
+    );
+
+    const transitions = transData.transitions || [];
+    if (transitions.length === 0) {
+      logError(`No transitions available for ${key} (current status: ${currentStatus})`);
+      return 2;
+    }
+
+    // Fuzzy match: case-insensitive, partial match
+    const target = targetStatus.toLowerCase();
+    const matches = transitions.filter((t) => {
+      const name = (t.name || '').toLowerCase();
+      return name === target || name.includes(target);
+    });
+
+    if (matches.length === 0) {
+      logError(`No transition matching "${targetStatus}" found for ${key}.`);
+      logError(`Available transitions:`);
+      for (const t of transitions) {
+        logError(`  - ${t.name} (id: ${t.id})`);
+      }
+      return 1;
+    }
+
+    if (matches.length > 1) {
+      // Check for exact match first
+      const exact = matches.find((t) => (t.name || '').toLowerCase() === target);
+      if (exact) {
+        matches.length = 0;
+        matches.push(exact);
+      } else {
+        logError(`Ambiguous transition "${targetStatus}" - multiple matches:`);
+        for (const t of matches) {
+          logError(`  - ${t.name} (id: ${t.id})`);
+        }
+        return 1;
+      }
+    }
+
+    const transition = matches[0];
+
+    // ── Build the fields patch from the new flags ──────────────────
+    // Done up-front so we can satisfy required fields declared by the
+    // transition without forcing the operator to a separate `update` call.
+    const patch = await buildRequiredFieldsPatch(args, client, textToAdf);
+
+    // Check for required fields not covered by what was provided.
+    const requiredFields = [];
+    if (transition.fields) {
+      for (const [fieldId, fieldDef] of Object.entries(transition.fields)) {
+        if (fieldDef.required) {
+          requiredFields.push({
+            id: fieldId,
+            name: fieldDef.name || fieldId,
+            schema: fieldDef.schema?.type || 'unknown',
+          });
+        }
+      }
+    }
+
+    const stillMissing = requiredFields.filter((f) => !(f.id in patch.fields));
+    if (stillMissing.length > 0) {
+      logError(yellow(`Transition "${transition.name}" requires additional fields:`));
+      for (const field of stillMissing) {
+        logError(`  - ${bold(field.name)} (${field.id}) - type: ${field.schema}`);
+      }
+      logError(dim(''));
+      logError(dim('Set them on this command via the new flags:'));
+      logError(dim('  --affected-services "<service name>"     (Affected services)'));
+      logError(dim('  --original-estimate 8h                    (Original Estimate)'));
+      logError(dim('  --field <field-id>=<value>                (any other required field)'));
+      return 1;
+    }
+
+    // Execute transition. Per Atlassian REST v3, fields go in the same body
+    // as the transition selector. We send `fields` only - `update` is used
+    // for edit-operations which aren't expressible via the convenience flags.
+    const body = { transition: { id: transition.id } };
+    if (Object.keys(patch.fields).length > 0) {
+      body.fields = patch.fields;
+    }
+
+    await client.post(
+      `/rest/api/3/issue/${encodeURIComponent(key)}/transitions`,
+      body
+    );
+
+    log(green(`${bold(key)}: ${currentStatus} → ${transition.name}`));
+    if (patch.changed.length > 0) {
+      log(`  Fields set on transition: ${patch.changed.join(', ')}`);
+    }
+    // Notify workspace (fail-silent, fire-and-forget). Test paths inject
+    // a no-op via deps.notifyWorkspace if needed.
+    (deps.notifyWorkspace || notifyWorkspaceAsync)();
+    return 0;
+  } catch (err) {
+    if (err instanceof JiraError) {
+      const wrapped = maybeWrapRequiredFieldError(err);
+      if (wrapped) {
+        logError(`jira transition: ${wrapped}`);
+      } else {
+        logError(`jira transition: ${err.message}`);
+      }
+      return err.exitCode;
+    }
+    throw err;
+  }
+}

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

@@ -0,0 +1,284 @@
+// update.mjs - Update Jira issue fields.
+//
+// At least one field must be provided.
+// Supports:
+//   -s SUMMARY                 Replace summary
+//   -d DESCRIPTION             Replace description (plain text → ADF)
+//   --assign USER              Assign to "me" | email | accountId
+//   --priority P               Replace priority (name or ID)
+//   --add-label NAME           Add a label (repeatable)
+//   --remove-label NAME        Remove a label (repeatable)
+//   --set-labels a,b,c         Replace label set (mutually exclusive with add/remove)
+//   --add-component NAME       Add a component by name (repeatable)
+//   --remove-component NAME    Remove a component by name (repeatable)
+//   --set-components a,b,c     Replace component set (mutually exclusive with add/remove)
+//   --field K=V                Set an arbitrary field (repeatable)
+//   --field-adf K=text         Set an ADF-typed field (repeatable)
+//   --affected-services NAME   Set Affected services customfield (resolved to ARI)
+//   --original-estimate DUR    Set timetracking.originalEstimate (Jira duration)
+//
+// Add/remove use Jira's edit-operations block ({"update": {...}}).
+// Replacement uses {"fields": {...}}.
+
+import { createClient, JiraError } from '../client.mjs';
+import { textToAdf } from '../adf.mjs';
+import { bold, green } from '../format.mjs';
+import {
+  asList,
+  parseCommaList,
+  validateLabels,
+  resolveComponents,
+  resolvePriority,
+  resolveAssignee,
+} from '../metadata.mjs';
+import {
+  buildRequiredFieldsPatch,
+  maybeWrapRequiredFieldError,
+} from '../required-fields.mjs';
+import { notifyWorkspaceAsync } from '../invalidate.mjs';
+
+const HELP = `jira update - Update issue fields
+
+Usage:
+  jira update <KEY> [-s SUMMARY] [-d DESCRIPTION] [--assign USER] [--priority P]
+                    [--add-label NAME] [--remove-label NAME] [--set-labels a,b,c]
+                    [--add-component NAME] [--remove-component NAME]
+                    [--set-components a,b,c]
+                    [--field K=V] [--field-adf K=text]
+                    [--affected-services NAME] [--original-estimate DURATION]
+
+Arguments:
+  KEY                       Issue key (e.g. AI-123)
+
+Options:
+  -s SUMMARY                New summary/title
+  -d DESCRIPTION            New description (plain text, converted to ADF)
+  --assign USER             Assign to user: "me", email, or accountId
+  --priority P              Set priority: name (e.g. "High") or ID (e.g. "2")
+  --add-label NAME          Add a label (repeatable)
+  --remove-label NAME       Remove a label (repeatable)
+  --set-labels a,b,c        Replace labels entirely (comma-separated;
+                            mutually exclusive with --add-label/--remove-label)
+  --add-component NAME      Add a component by name (repeatable; resolved
+                            against the target project's component list)
+  --remove-component NAME   Remove a component by name (repeatable)
+  --set-components a,b,c    Replace components entirely (comma-separated;
+                            mutually exclusive with --add-component/--remove-component)
+  --field K=V               Set an arbitrary field (repeatable). V is parsed
+                            as JSON if it looks like JSON, otherwise string.
+                            Reserved keys must use their dedicated flags.
+  --field-adf K=text        Set an ADF-typed field; text is converted to ADF.
+                            (Repeatable.)
+  --affected-services NAME  Set the "Affected services" customfield. NAME is
+                            the service display name; the CLI resolves it to
+                            the ARI via the service-registry autocomplete
+                            endpoint. Required by some workflows.
+  --original-estimate DUR   Set timetracking.originalEstimate. DUR uses
+                            Jira duration syntax: "8h", "30m", "1d 4h".
+                            Required by some workflows.
+
+At least one field/operation must be provided. Labels cannot contain whitespace.
+
+Priority values:
+  Blocker (1), Serious (2), Medium (3), Minor (4), Trivial (5)
+`;
+
+// Map priority names (lowercase) to Jira priority IDs (kept for back-compat /
+// offline use when the legacy --priority short path is hit without an API call).
+const PRIORITY_MAP = {
+  blocker: '1',
+  highest: '1',
+  serious: '2',
+  high: '2',
+  medium: '3',
+  minor: '4',
+  low: '4',
+  trivial: '5',
+  lowest: '5',
+};
+
+/**
+ * Run the update command.
+ *
+ * @param {string[]} argv  Remaining args after 'update'
+ * @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 update <KEY> [-s SUMMARY] [-d DESC] [--assign USER] [--priority P]');
+    logError('                       [--add-label NAME] [--remove-label NAME] [--set-labels a,b,c]');
+    logError('                       [--add-component NAME] [--remove-component NAME] [--set-components a,b,c]');
+    logError('                       [--field K=V] [--field-adf K=text]');
+    logError('                       [--affected-services NAME] [--original-estimate DUR]');
+    return 1;
+  }
+
+  // ── Gather flag values ─────────────────────────────────────────────
+  const summary = args.s || args.summary;
+  const description = args.d || args.description;
+  const assign = args.assign;
+  const priority = args.priority;
+
+  const addLabels = asList(args['add-label']);
+  const removeLabels = asList(args['remove-label']);
+  const setLabelsRaw = args['set-labels'];
+  const setLabels = setLabelsRaw != null ? parseCommaList(setLabelsRaw) : null;
+
+  const addComponents = asList(args['add-component']);
+  const removeComponents = asList(args['remove-component']);
+  const setComponentsRaw = args['set-components'];
+  const setComponents = setComponentsRaw != null ? parseCommaList(setComponentsRaw) : null;
+
+  // ── Mutually-exclusive checks (usage error, exit 1) ────────────────
+  if (setLabels !== null && (addLabels.length > 0 || removeLabels.length > 0)) {
+    logError('jira update: --set-labels is mutually exclusive with --add-label / --remove-label');
+    return 1;
+  }
+  if (setComponents !== null && (addComponents.length > 0 || removeComponents.length > 0)) {
+    logError('jira update: --set-components is mutually exclusive with --add-component / --remove-component');
+    return 1;
+  }
+
+  // ── Local label validation (cheap fail-fast) ───────────────────────
+  try {
+    validateLabels(addLabels);
+    validateLabels(removeLabels);
+    if (setLabels) validateLabels(setLabels);
+  } catch (err) {
+    if (err instanceof JiraError) {
+      logError(`jira update: ${err.message}`);
+      return err.exitCode;
+    }
+    throw err;
+  }
+
+  // ── Build payload ──────────────────────────────────────────────────
+  const fields = {};
+  const update = {};
+  const changed = [];
+
+  if (summary) {
+    fields.summary = summary;
+    changed.push('summary');
+  }
+  if (description) {
+    fields.description = textToAdf(description);
+    changed.push('description');
+  }
+
+  // Labels - set (fields) vs add/remove (update)
+  if (setLabels !== null) {
+    fields.labels = setLabels;
+    changed.push('labels (set)');
+  } else if (addLabels.length > 0 || removeLabels.length > 0) {
+    update.labels = [
+      ...addLabels.map((v) => ({ add: v })),
+      ...removeLabels.map((v) => ({ remove: v })),
+    ];
+    if (addLabels.length > 0) changed.push(`labels +${addLabels.length}`);
+    if (removeLabels.length > 0) changed.push(`labels -${removeLabels.length}`);
+  }
+
+  const client = deps.client || createClient();
+
+  // Need the project key for component resolution. Derive it from the
+  // issue key (everything before the dash). Jira keys are PROJECT-NUM.
+  const projectKey = String(key).split('-')[0].toUpperCase();
+
+  try {
+    // Components - set (fields) vs add/remove (update). Both paths need
+    // name → id resolution via the project's components list.
+    if (setComponents !== null) {
+      const resolved = await resolveComponents(client, projectKey, setComponents);
+      fields.components = resolved.map((c) => ({ id: c.id }));
+      changed.push('components (set)');
+    } else if (addComponents.length > 0 || removeComponents.length > 0) {
+      const all = [...addComponents, ...removeComponents];
+      const resolved = await resolveComponents(client, projectKey, all);
+      const adds = resolved.slice(0, addComponents.length);
+      const removes = resolved.slice(addComponents.length);
+      update.components = [
+        ...adds.map((c) => ({ add: { id: c.id } })),
+        ...removes.map((c) => ({ remove: { id: c.id } })),
+      ];
+      if (adds.length > 0) changed.push(`components +${adds.length}`);
+      if (removes.length > 0) changed.push(`components -${removes.length}`);
+    }
+
+    // Assignee
+    if (assign) {
+      const accountId = await resolveAssignee(client, assign);
+      fields.assignee = { accountId };
+      changed.push('assignee');
+    }
+
+    // Priority - try the static name→id map first (no API call). For
+    // numeric IDs, pass through directly. Fall back to a live lookup only
+    // when the name is unknown locally, so unfamiliar Jira-instance-specific
+    // priorities still resolve.
+    if (priority) {
+      if (/^\d+$/.test(priority)) {
+        fields.priority = { id: priority };
+      } else {
+        const lower = priority.toLowerCase();
+        if (PRIORITY_MAP[lower]) {
+          fields.priority = { id: PRIORITY_MAP[lower] };
+        } else {
+          const resolved = await resolvePriority(client, priority);
+          fields.priority = { id: resolved.id };
+        }
+      }
+      changed.push('priority');
+    }
+
+    // Generic --field / --field-adf / --affected-services / --original-estimate.
+    // These all target `fields` (never `update`), so just merge in.
+    const patch = await buildRequiredFieldsPatch(args, client, textToAdf);
+    Object.assign(fields, patch.fields);
+    changed.push(...patch.changed);
+
+    // ── Final sanity: at least one operation queued ──────────────────
+    if (Object.keys(fields).length === 0 && Object.keys(update).length === 0) {
+      logError('No fields to update. Provide at least one of:');
+      logError('  -s, -d, --assign, --priority,');
+      logError('  --add-label, --remove-label, --set-labels,');
+      logError('  --add-component, --remove-component, --set-components,');
+      logError('  --field, --field-adf, --affected-services, --original-estimate');
+      return 1;
+    }
+
+    const payload = {};
+    if (Object.keys(fields).length > 0) payload.fields = fields;
+    if (Object.keys(update).length > 0) payload.update = update;
+
+    await client.put(`/rest/api/3/issue/${encodeURIComponent(key)}`, payload);
+    log(green(`${bold(key)} updated successfully.`));
+    log(`  Changes: ${changed.join(', ')}`);
+
+    (deps.notifyWorkspace || notifyWorkspaceAsync)();
+    return 0;
+  } catch (err) {
+    if (err instanceof JiraError) {
+      const wrapped = maybeWrapRequiredFieldError(err);
+      if (wrapped) {
+        logError(`jira update: ${wrapped}`);
+      } else {
+        logError(`jira update: ${err.message}`);
+      }
+      return err.exitCode;
+    }
+    throw err;
+  }
+}