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

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

@@ -0,0 +1,72 @@
+// invalidate.mjs - Notify the workspace server that Jira state has changed.
+//
+// After a Jira write command (create / update / transition / comment / cancel),
+// the CLI POSTs to /__api/jira/invalidate on the local workspace server. The
+// server clears its 60-second cache buckets and pushes an SSE event so any
+// open /jira.html tab re-fetches immediately.
+//
+// Transport lives in the shared client at
+// operator/extensions/tools/invalidate-client/src/client.mjs; this module
+// only binds the jira-specific endpoint, body shape, and disable flag. The
+// contract is unchanged:
+//   - Fail-silent. The CLI's primary job is to mutate Jira; the workspace
+//     is a nice-to-have. If the workspace server is stopped, the wrong port
+//     is configured, or the network call hangs, the CLI must not slow down
+//     and must not surface an error to the operator.
+//   - Non-blocking by design. Fire the request, wait at most 500ms, then
+//     return regardless of outcome.
+//   - Zero runtime deps. Uses Node 20+ globalThis.fetch and AbortController.
+//
+// Disable mechanism: set DEX_JIRA_INVALIDATE=0 to skip the notify (useful for
+// test environments or if the workspace is intentionally absent).
+
+import {
+  notifyInvalidate,
+  notifyInvalidateAsync,
+} from '../common/invalidate-client.mjs';
+
+const ENDPOINT = '/__api/jira/invalidate';
+const DISABLE_ENV = 'DEX_JIRA_INVALIDATE';
+
+function toClientOpts(opts = {}) {
+  return {
+    endpoint: ENDPOINT,
+    disableEnv: DISABLE_ENV,
+    body: { views: Array.isArray(opts.views) ? opts.views : [] },
+    port: opts.port,
+    timeoutMs: opts.timeoutMs,
+    fetchImpl: opts.fetchImpl,
+  };
+}
+
+/**
+ * Notify the workspace that Jira state changed. Non-blocking, fail-silent.
+ *
+ * @param {object} [opts]
+ * @param {string[]} [opts.views]  Cache buckets to clear. Omit / empty to
+ *                                  clear all (the typical case).
+ * @param {number}   [opts.port]   Override the resolved workspace port
+ *                                  (test injection).
+ * @param {number}   [opts.timeoutMs]  Override the request timeout.
+ * @param {Function} [opts.fetchImpl]  Override fetch (test injection).
+ * @returns {Promise<{ok: boolean, error?: string}>}  Always resolves; never
+ *                                                     throws.
+ */
+export function notifyWorkspace(opts = {}) {
+  return notifyInvalidate(toClientOpts(opts));
+}
+
+/**
+ * Fire-and-forget wrapper. Returns immediately; the notify runs in the
+ * background. Suitable for use at the tail of a CLI command where we
+ * don't want to delay the user-visible exit by even the timeout window.
+ *
+ * The returned promise can be awaited in tests to deterministically
+ * observe completion; in production the CLI just doesn't await it.
+ *
+ * @param {object} [opts]  Same shape as notifyWorkspace.
+ * @returns {Promise<{ok: boolean, error?: string}>}
+ */
+export function notifyWorkspaceAsync(opts = {}) {
+  return notifyInvalidateAsync(toClientOpts(opts));
+}

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

@@ -0,0 +1,225 @@
+// metadata.mjs - Shared helpers for resolving Jira metadata fields.
+//
+// Resolves component names → ids (scoped to a project), priority names → ids,
+// and assignee emails → accountIds. Also validates label values.
+//
+// Each resolver takes an injected `client` so it stays testable with mocked
+// fetch via `createClient({ fetchFn })`. None of these helpers touch the vault.
+
+import { JiraError } from './client.mjs';
+
+// ── Labels ───────────────────────────────────────────────────────────
+
+/**
+ * Jira labels cannot contain whitespace. Validate locally and throw a
+ * usage-error (exit code 1) on first violation so the CLI fails fast
+ * without burning an API call.
+ *
+ * @param {string[]} labels  Label values to check
+ * @throws {JiraError}       exitCode 1 if any label is invalid
+ */
+export function validateLabels(labels) {
+  for (const label of labels) {
+    if (typeof label !== 'string' || label.length === 0) {
+      throw new JiraError(`Invalid label: empty value`, 1);
+    }
+    if (/\s/.test(label)) {
+      throw new JiraError(
+        `Invalid label "${label}": Jira labels cannot contain whitespace`,
+        1
+      );
+    }
+  }
+}
+
+/**
+ * Parse a `--set-labels a,b,c` value into an array. Commas separate;
+ * surrounding whitespace on each label is trimmed. Empty entries are
+ * dropped. Labels themselves cannot contain whitespace (validated
+ * downstream).
+ *
+ * @param {string} raw  Raw flag value (comma-separated list)
+ * @returns {string[]}  Cleaned label list
+ */
+export function parseCommaList(raw) {
+  if (raw == null) return [];
+  return String(raw)
+    .split(',')
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
+// ── Components ───────────────────────────────────────────────────────
+
+/**
+ * Fetch the components list for a project and return a name→id map.
+ * Names are matched case-insensitively; the original casing of the
+ * first encountered match is preserved in the map keys.
+ *
+ * @param {object} client     Jira client
+ * @param {string} projectKey Project key (e.g. "PROJ")
+ * @returns {Promise<Map<string, { id: string, name: string }>>}
+ *                            Map keyed by lowercased name → { id, name }
+ */
+export async function listProjectComponents(client, projectKey) {
+  const path = `/rest/api/3/project/${encodeURIComponent(projectKey)}/components`;
+  const { data } = await client.get(path);
+  // The endpoint returns a bare array of components.
+  const components = Array.isArray(data) ? data : (data?.values || []);
+  const map = new Map();
+  for (const c of components) {
+    if (c && c.name && c.id != null) {
+      map.set(String(c.name).toLowerCase(), { id: String(c.id), name: c.name });
+    }
+  }
+  return map;
+}
+
+/**
+ * Resolve component names to { id, name } objects via the project's
+ * components list. Throws JiraError(2) on the first unknown name, with
+ * a message listing the valid component names.
+ *
+ * @param {object} client       Jira client
+ * @param {string} projectKey   Project key
+ * @param {string[]} names      Component names to resolve
+ * @returns {Promise<{ id: string, name: string }[]>}
+ */
+export async function resolveComponents(client, projectKey, names) {
+  if (!names || names.length === 0) return [];
+  const map = await listProjectComponents(client, projectKey);
+  const resolved = [];
+  for (const raw of names) {
+    const key = String(raw).toLowerCase();
+    const hit = map.get(key);
+    if (!hit) {
+      const valid = [...map.values()].map((c) => c.name).sort();
+      const list = valid.length > 0 ? valid.join(', ') : '(none defined on project)';
+      throw new JiraError(
+        `Unknown component "${raw}" in project ${projectKey}. Valid: ${list}`,
+        2
+      );
+    }
+    resolved.push(hit);
+  }
+  return resolved;
+}
+
+// ── Priorities ───────────────────────────────────────────────────────
+
+/**
+ * Fetch the global priority list and return a name→{ id, name } map
+ * keyed by lowercased name. Numeric priority IDs are also indexed so
+ * callers can pass an ID directly.
+ *
+ * @param {object} client  Jira client
+ * @returns {Promise<Map<string, { id: string, name: string }>>}
+ */
+export async function listPriorities(client) {
+  const { data } = await client.get('/rest/api/3/priority');
+  const priorities = Array.isArray(data) ? data : (data?.values || []);
+  const map = new Map();
+  for (const p of priorities) {
+    if (p && p.name && p.id != null) {
+      map.set(String(p.name).toLowerCase(), { id: String(p.id), name: p.name });
+      map.set(String(p.id), { id: String(p.id), name: p.name });
+    }
+  }
+  return map;
+}
+
+/**
+ * Resolve a single priority name (or numeric ID) to { id, name }.
+ * Throws JiraError(2) on unknown.
+ *
+ * @param {object} client  Jira client
+ * @param {string} value   Priority name (e.g. "High") or numeric id
+ * @returns {Promise<{ id: string, name: string }>}
+ */
+export async function resolvePriority(client, value) {
+  const map = await listPriorities(client);
+  const hit = map.get(String(value).toLowerCase());
+  if (!hit) {
+    // Build a unique, sorted list of names for the error message.
+    const seen = new Set();
+    const names = [];
+    for (const v of map.values()) {
+      if (!seen.has(v.name)) {
+        seen.add(v.name);
+        names.push(v.name);
+      }
+    }
+    throw new JiraError(
+      `Unknown priority "${value}". Valid: ${names.sort().join(', ')}`,
+      2
+    );
+  }
+  return hit;
+}
+
+// ── Assignee ─────────────────────────────────────────────────────────
+
+/**
+ * Resolve an assignee identifier to a Jira accountId.
+ *
+ * - If the value looks like an email (contains @), search by email and
+ *   return the matching accountId.
+ * - If the value is "me", fetch /myself.
+ * - Otherwise, treat as an accountId and pass straight through.
+ *
+ * Throws JiraError(2) if email resolution finds zero or multiple matches.
+ *
+ * @param {object} client  Jira client
+ * @param {string} value   "me", an email, or an accountId
+ * @returns {Promise<string>}  accountId
+ */
+export async function resolveAssignee(client, value) {
+  if (value === 'me') {
+    const { data } = await client.get('/rest/api/3/myself');
+    if (!data || !data.accountId) {
+      throw new JiraError('Failed to resolve current user accountId', 2);
+    }
+    return data.accountId;
+  }
+
+  if (typeof value === 'string' && value.includes('@')) {
+    const path = `/rest/api/3/user/search?query=${encodeURIComponent(value)}`;
+    const { data } = await client.get(path);
+    const users = Array.isArray(data) ? data : [];
+    if (users.length === 0) {
+      throw new JiraError(`No user found for email "${value}"`, 2);
+    }
+    // Prefer an exact emailAddress match; if a single result, use it.
+    const exact = users.find((u) => (u.emailAddress || '').toLowerCase() === value.toLowerCase());
+    const pick = exact || (users.length === 1 ? users[0] : null);
+    if (!pick) {
+      const candidates = users.map((u) => `${u.displayName || '?'} <${u.emailAddress || '?'}>`);
+      throw new JiraError(
+        `Ambiguous user "${value}" - multiple matches: ${candidates.join('; ')}`,
+        2
+      );
+    }
+    if (!pick.accountId) {
+      throw new JiraError(`User "${value}" has no accountId`, 2);
+    }
+    return pick.accountId;
+  }
+
+  // Assume accountId; pass through.
+  return value;
+}
+
+// ── Helpers for assembling flag values into arrays ───────────────────
+
+/**
+ * Coerce a repeated-flag value (string | string[] | undefined) into an
+ * array of strings. Returns [] for undefined or empty values.
+ *
+ * @param {string|string[]|undefined} value
+ * @returns {string[]}
+ */
+export function asList(value) {
+  if (value == null) return [];
+  if (Array.isArray(value)) return value.map((v) => String(v));
+  return [String(value)];
+}

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

@@ -0,0 +1,334 @@
+// required-fields.mjs - Shared helpers for the sites that require extra fields on ticket create/update.
+//
+// Three concerns:
+//
+//  1. Generic --field / --field-adf parsing (lifted from prior --field work
+//     so create, update, and transition all share the same shape).
+//
+//  2. Convenience flags for common required fields (--ticket-type, --scope, --initiative).
+//       --affected-services <name>   → resolved to customfield_<id> dynamically
+//                                       with service-registry ARI lookup
+//       --original-estimate <dur>    → timetracking.originalEstimate
+//       (Ticket Type is already covered by `-t TYPE` on create.)
+//
+//  3. Error wrapping - when the API returns a "Please complete <X> field"
+//     payload, wrap the error with a hint naming the three usual culprits
+//     and the exact flags to set them.
+//
+// No live API state is cached across CLI invocations; caching is per-process
+// only (a single jira CLI call may hit the API multiple times during one
+// command, e.g. resolve + post).
+
+import { JiraError } from './client.mjs';
+
+// ── Reserved keys ────────────────────────────────────────────────────
+//
+// Generic --field is intentionally a back door; some fields are NOT safe to
+// drop through it because the CLI manages them via dedicated, validated
+// flags (labels, components, priority, assignee, etc.). Rejecting the
+// reserved set forces the operator onto the validating path.
+
+export const RESERVED_FIELD_KEYS = new Set([
+  'summary',
+  'description',
+  'labels',
+  'components',
+  'priority',
+  'assignee',
+  'project',
+  'issuetype',
+  'timetracking',  // managed via --original-estimate
+]);
+
+// ── Field discovery (id ↔ name) ──────────────────────────────────────
+
+const fieldCacheByKey = new Map();   // name (lowercased) → field id
+
+/**
+ * Resolve a Jira field by display name to its id (e.g. customfield_NNNNN).
+ * Returns the id string; throws JiraError(2) if no match.
+ *
+ * Matching: case-insensitive exact match on the field's `name`.
+ *
+ * @param {object} client     Jira client
+ * @param {string} fieldName  Field display name (e.g. "Affected services")
+ * @returns {Promise<string>} Field id
+ */
+export async function discoverFieldId(client, fieldName) {
+  const key = String(fieldName).toLowerCase();
+  if (fieldCacheByKey.has(key)) return fieldCacheByKey.get(key);
+
+  const { data } = await client.get('/rest/api/3/field');
+  const fields = Array.isArray(data) ? data : (data?.values || []);
+  for (const f of fields) {
+    if (f && f.name && String(f.name).toLowerCase() === key) {
+      fieldCacheByKey.set(key, f.id);
+      return f.id;
+    }
+  }
+
+  throw new JiraError(
+    `Unknown Jira field "${fieldName}" - not found in /rest/api/3/field`,
+    2
+  );
+}
+
+// Test-only: reset the cache between tests. Not exported publicly elsewhere.
+export function _resetFieldCacheForTests() {
+  fieldCacheByKey.clear();
+}
+
+// ── Service-registry ARI resolution (Affected Services) ──────────────
+
+const serviceAriCache = new Map();   // service name (lowercased) → ari
+
+/**
+ * Resolve an "Affected services" value (a service display name) to its ARI.
+ *
+ * The Affected Services field is a `service-entity-field` array; values are
+ * Atlassian Resource Identifiers (ARIs) of services in the workspace's
+ * service registry. We resolve by querying the autocomplete endpoint:
+ *
+ *   GET /rest/service-registry-api/service?query=<name>
+ *
+ * and matching the response's `name` field (case-insensitive exact). If the
+ * caller passes a value that already looks like an ARI, we pass it through
+ * unmodified - useful when scripting against known IDs.
+ *
+ * @param {object} client  Jira client
+ * @param {string} name    Service display name OR an existing ARI
+ * @returns {Promise<string>}  ARI string
+ */
+export async function resolveAffectedServiceAri(client, name) {
+  const value = String(name);
+
+  // Already an ARI? Pass through.
+  if (value.startsWith('ari:')) return value;
+
+  const key = value.toLowerCase();
+  if (serviceAriCache.has(key)) return serviceAriCache.get(key);
+
+  const path = `/rest/service-registry-api/service?query=${encodeURIComponent(value)}`;
+  const { data } = await client.get(path);
+  const services = Array.isArray(data?.services) ? data.services : (Array.isArray(data) ? data : []);
+
+  // Prefer exact case-insensitive name match.
+  const exact = services.find((s) => s && s.name && String(s.name).toLowerCase() === key);
+  if (exact && exact.id) {
+    serviceAriCache.set(key, exact.id);
+    return exact.id;
+  }
+
+  // No exact hit - list candidates to help the user.
+  const candidates = services.map((s) => s?.name).filter(Boolean).slice(0, 10);
+  const list = candidates.length > 0 ? candidates.join(', ') : '(none returned)';
+  throw new JiraError(
+    `Unknown Affected service "${name}". Candidates from registry: ${list}`,
+    2
+  );
+}
+
+// Test-only.
+export function _resetServiceAriCacheForTests() {
+  serviceAriCache.clear();
+}
+
+// ── Generic --field / --field-adf parsing ────────────────────────────
+
+/**
+ * Parse a single `--field K=V` argument into `{ key, value }`.
+ *
+ * V is auto-detected:
+ *   - if it parses as JSON and the result is an object/array/number/boolean,
+ *     it's used as-is;
+ *   - otherwise it's used as a plain string.
+ *
+ * `K` cannot be a member of RESERVED_FIELD_KEYS - those are managed by
+ * dedicated flags and must not be set via the generic back door.
+ *
+ * @param {string} raw  e.g. "customfield_12345=foo" or 'customfield_12345={"value":"x"}'
+ * @returns {{ key: string, value: any }}
+ * @throws {JiraError} exitCode 1 on bad shape or reserved key
+ */
+export function parseFieldFlag(raw) {
+  if (typeof raw !== 'string' || raw.length === 0) {
+    throw new JiraError(`--field requires K=V (got empty value)`, 1);
+  }
+  const eq = raw.indexOf('=');
+  if (eq <= 0) {
+    throw new JiraError(`--field "${raw}" must be of the form K=V`, 1);
+  }
+  const key = raw.slice(0, eq).trim();
+  const rawValue = raw.slice(eq + 1);
+
+  if (!key) {
+    throw new JiraError(`--field "${raw}" has empty key`, 1);
+  }
+  if (RESERVED_FIELD_KEYS.has(key)) {
+    throw new JiraError(
+      `--field "${key}" is reserved; use the dedicated flag instead ` +
+      `(e.g. -s/-d/--priority/--add-label/--original-estimate)`,
+      1
+    );
+  }
+
+  // Try JSON first; fall back to string.
+  let value = rawValue;
+  const trimmed = rawValue.trim();
+  if (
+    trimmed.startsWith('{') ||
+    trimmed.startsWith('[') ||
+    trimmed === 'true' || trimmed === 'false' || trimmed === 'null' ||
+    /^-?\d+(\.\d+)?$/.test(trimmed)
+  ) {
+    try {
+      value = JSON.parse(trimmed);
+    } catch {
+      // Not JSON - keep as string.
+    }
+  }
+
+  return { key, value };
+}
+
+/**
+ * Parse a single `--field-adf K=text` argument. The text is converted to
+ * ADF (via the caller-provided `textToAdf`) and packaged the same way as
+ * --field. Reserved keys are rejected for the same reasons.
+ *
+ * @param {string} raw          K=text
+ * @param {Function} textToAdf  Conversion function (injected for testability)
+ * @returns {{ key: string, value: object }}
+ */
+export function parseFieldAdfFlag(raw, textToAdf) {
+  if (typeof raw !== 'string' || raw.length === 0) {
+    throw new JiraError(`--field-adf requires K=text (got empty value)`, 1);
+  }
+  const eq = raw.indexOf('=');
+  if (eq <= 0) {
+    throw new JiraError(`--field-adf "${raw}" must be of the form K=text`, 1);
+  }
+  const key = raw.slice(0, eq).trim();
+  const text = raw.slice(eq + 1);
+
+  if (!key) {
+    throw new JiraError(`--field-adf "${raw}" has empty key`, 1);
+  }
+  if (RESERVED_FIELD_KEYS.has(key)) {
+    throw new JiraError(
+      `--field-adf "${key}" is reserved; use the dedicated flag instead`,
+      1
+    );
+  }
+
+  return { key, value: textToAdf(text) };
+}
+
+// ── Required-field patch builder ─────────────────────────────────────
+
+/**
+ * Build the `fields` object increments contributed by the new flags
+ * (--field / --field-adf / --affected-services / --original-estimate).
+ *
+ * Caller passes in:
+ *   - args: parsed CLI args (output of parseArgs)
+ *   - client: Jira client (used for field-id / service-ARI resolution)
+ *   - textToAdf: ADF conversion fn (injected to keep this module decoupled)
+ *
+ * Returns `{ fields }` - an object suitable for merging into the existing
+ * `fields` payload on create / update / transition.
+ *
+ * Throws JiraError on bad shape or resolution failure.
+ *
+ * @param {object} args
+ * @param {object} client
+ * @param {Function} textToAdf
+ * @returns {Promise<{ fields: object, changed: string[] }>}
+ */
+export async function buildRequiredFieldsPatch(args, client, textToAdf) {
+  const fields = {};
+  const changed = [];
+
+  // --field K=V (repeatable). asList-style coercion.
+  const rawFields = toArray(args.field);
+  for (const raw of rawFields) {
+    const { key, value } = parseFieldFlag(raw);
+    fields[key] = value;
+    changed.push(`field:${key}`);
+  }
+
+  // --field-adf K=text (repeatable).
+  const rawAdfFields = toArray(args['field-adf']);
+  for (const raw of rawAdfFields) {
+    const { key, value } = parseFieldAdfFlag(raw, textToAdf);
+    fields[key] = value;
+    changed.push(`field-adf:${key}`);
+  }
+
+  // --affected-services <name> (single, by current Jira field cardinality).
+  // We accept repeated flags too in case the field's cardinality ever changes
+  // - the cost of treating it as a list is the same and it's forward-safe.
+  const services = toArray(args['affected-services']);
+  if (services.length > 0) {
+    const fieldId = await discoverFieldId(client, 'Affected services');
+    const aris = [];
+    for (const s of services) {
+      const ari = await resolveAffectedServiceAri(client, s);
+      aris.push({ id: ari });
+    }
+    fields[fieldId] = aris;
+    changed.push('affected-services');
+  }
+
+  // --original-estimate <duration>. Duration must be a Jira time string.
+  if (args['original-estimate']) {
+    const duration = String(args['original-estimate']);
+    fields.timetracking = { originalEstimate: duration };
+    changed.push('original-estimate');
+  }
+
+  return { fields, changed };
+}
+
+function toArray(v) {
+  if (v == null) return [];
+  if (Array.isArray(v)) return v.map((x) => String(x));
+  return [String(v)];
+}
+
+// ── "Please complete X field" error wrapping ─────────────────────────
+
+const COMPLETE_FIELD_RE = /Please complete (?:the )?(.+?) field/i;
+
+/**
+ * If a JiraError is your site's "Please complete X field" gate,
+ * return a wrapped message that names the three usual culprits and the
+ * exact flag to set each. Otherwise return null (caller should re-raise
+ * the original).
+ *
+ * @param {Error|JiraError} err
+ * @returns {string|null}  wrapped message, or null
+ */
+export function maybeWrapRequiredFieldError(err) {
+  if (!err || typeof err.message !== 'string') return null;
+  if (!COMPLETE_FIELD_RE.test(err.message)) return null;
+
+  const lines = [
+    err.message,
+    '',
+    'Hint: your site requires these fields populated before',
+    'transitioning past Qualification:',
+    '  - Ticket Type        - `--field customfield_11535=\'{"value":"Tech Roadmap"}\'`',
+    '                         (select customfield; valid options include',
+    '                          "Tech Roadmap", "Technical Debt", "Product Roadmap",',
+    '                          "Incident Response", "Non Development Tasks";',
+    '                          distinct from -t issuetype on `create`)',
+    '  - Affected Services  - `--affected-services "Artificial Intelligence Services"`',
+    '                         (or e.g. `--affected-services "WESPA (Compass ARI)"`)',
+    '  - Original Estimate  - `--original-estimate 8h` (Jira duration syntax)',
+    '',
+    'Re-run the same command with the missing flag, or backfill via',
+    '`jira update <KEY> --original-estimate 8h --affected-services "..."`.',
+  ];
+  return lines.join('\n');
+}