Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* JIRA API Service
* Supports multiple JIRA instances with Personal Access Tokens
*/
import fs from 'fs/promises';
import { createBoundedStateMap } from '../lib/boundedStateMap.js';
import { createHttpClient } from '../lib/httpClient.js';
import { ServerError } from '../lib/errorHandler.js';
import { createSingleFlight } from '../lib/singleFlight.js';
import path from 'path';
import { atomicWrite, ensureDir, PATHS, readJSONFile } from '../lib/fileUtils.js';
import { hostFromOriginUrl } from '../lib/workTracker.js';
import { countConfiguredInstances } from '../lib/instanceFeatureRegistry.js';
const instanceNotFound = (instanceId) =>
new ServerError(`JIRA instance ${instanceId} not found`, { status: 404, code: 'NOT_FOUND' });
const JIRA_CONFIG_FILE = path.join(PATHS.data, 'jira.json');
// Resolved Cloud user-search results are stable until the instance credentials
// change, and ticket creation can happen repeatedly in one run. Keep only
// positive results in a bounded per-instance cache so a transient failure or an
// initially hidden user can recover on the next ticket.
const cloudAssigneeCache = new Map();
const cloudAssigneeLookupFlight = createSingleFlight();
function getCloudAssigneeCache(instanceId) {
let instanceCache = cloudAssigneeCache.get(instanceId);
if (!instanceCache) {
instanceCache = createBoundedStateMap();
cloudAssigneeCache.set(instanceId, instanceCache);
}
return instanceCache;
}
export function clearCloudAssigneeCache(instanceId) {
if (instanceId === undefined) cloudAssigneeCache.clear();
else cloudAssigneeCache.delete(instanceId);
}
// Whether this install has any JIRA instance configured. Read-only on purpose:
// unlike getInstances() it never seeds an empty config file, because the
// instance-feature registry calls it just to decide whether the JIRA nav
// entries should appear on a fresh install.
//
// `strict` so a PRESENT-but-corrupt config throws instead of reading as the
// empty default. The caller turns a throw into "detection failed" and falls back
// to the shipped default; without it an unparseable jira.json would report a
// confident "no instances" and silently hide the JIRA navigation. A genuinely
// absent file still returns the empty default — absent is a trustworthy empty.
export async function hasConfiguredInstances() {
const config = await readJSONFile(JIRA_CONFIG_FILE, { instances: {} }, { logError: false, strict: true });
return countConfiguredInstances(config, 'jira.json') > 0;
}
export const escapeJql = (s) => String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"');
/**
* Get JIRA instances configuration
*/
export async function getInstances() {
try {
const content = await fs.readFile(JIRA_CONFIG_FILE, 'utf-8');
return JSON.parse(content);
} catch (error) {
if (error.code === 'ENOENT') {
// Initialize with empty config
const defaultConfig = { instances: {} };
await saveInstances(defaultConfig);
return defaultConfig;
}
throw error;
}
}
/**
* Save JIRA instances configuration
*/
export async function saveInstances(config) {
await atomicWrite(JIRA_CONFIG_FILE, config);
}
/**
* Add or update JIRA instance
*/
export async function upsertInstance(instanceId, instanceData) {
const config = await getInstances();
const existing = config.instances[instanceId];
config.instances[instanceId] = {
id: instanceId,
name: instanceData.name,
baseUrl: instanceData.baseUrl,
email: instanceData.email,
apiToken: instanceData.apiToken || existing?.apiToken, // Server/DC PAT (sent as Bearer) or Cloud API token (sent as Basic email:token)
tokenUpdatedAt: instanceData.apiToken && instanceData.apiToken !== existing?.apiToken
? new Date().toISOString()
: (existing?.tokenUpdatedAt || new Date().toISOString()),
createdAt: existing?.createdAt || new Date().toISOString(),
updatedAt: new Date().toISOString()
};
await saveInstances(config);
// A changed token can authenticate as a different account.
clearCloudAssigneeCache(instanceId);
clearCurrentUserCache(instanceId);
return config.instances[instanceId];
}
/**
* Delete JIRA instance
*/
export async function deleteInstance(instanceId) {
const config = await getInstances();
delete config.instances[instanceId];
await saveInstances(config);
clearCloudAssigneeCache(instanceId);
clearCurrentUserCache(instanceId);
}
/**
* Whether a JIRA instance is Jira Cloud (*.atlassian.net) vs Server / Data Center.
* Uses the shared no-throw host extractor (returns null on unparseable input) so a
* hand-edited jira.json can't throw here.
*/
export function isCloudInstance(baseUrl) {
const host = hostFromOriginUrl(baseUrl);
return !!host && /(^|\.)atlassian\.net$/i.test(host);
}
/**
* Build the Authorization header for a JIRA instance.
* - Jira Cloud authenticates a personal API token via HTTP Basic (base64 "email:token").
* - Jira Server / Data Center authenticates a Personal Access Token (PAT) via Bearer.
* Detected by host so Server and Cloud instances can coexist during a migration.
*/
export function jiraAuthHeader(instance) {
if (isCloudInstance(instance.baseUrl)) {
return `Basic ${Buffer.from(`${instance.email}:${instance.apiToken}`).toString('base64')}`;
}
return `Bearer ${instance.apiToken}`;
}
/**
* Create HTTP client for JIRA instance
*/
export function createJiraClient(instance) {
if (instance.allowSelfSigned) {
console.warn(`⚠️ JIRA instance ${instance.name || instance.id} using allowSelfSigned — TLS verification disabled`);
}
const base = createHttpClient({
baseURL: instance.baseUrl,
headers: {
'Authorization': jiraAuthHeader(instance),
'Content-Type': 'application/json',
'Accept': 'application/json'
},
timeout: 30000,
allowSelfSigned: instance.allowSelfSigned
});
// Expired/invalid token surfaces differently per instance type, so detection is
// instance-type-aware alongside jiraAuthHeader — both funnel to one friendly error:
// - Jira Server/DC: 200 response whose body is the HTML login page (not JSON).
// - Jira Cloud: JSON 401 (createHttpClient throws HTTP 401), never an HTML page.
const isCloud = isCloudInstance(instance.baseUrl);
const expiredTokenError = () => {
const err = new Error('JIRA token expired or invalid — regenerate your token (Server: PAT; Cloud: API token).');
err.status = 401;
return err;
};
// Success path: only Server serves an HTML login page in place of JSON, so gate the
// heuristic to Server — a Cloud JSON payload can't accidentally trip on "<!DOCTYPE".
const checkToken = res => {
if (!isCloud && typeof res.data === 'string' && res.data.includes('<!DOCTYPE')) {
throw expiredTokenError();
}
return res;
};
// Error path: a 401 (Cloud's expired-token signal, and Server's when it 401s rather
// than serving HTML) maps to the same friendly error. Other errors bubble unchanged.
const mapAuthError = err => {
if (err?.status === 401) throw expiredTokenError();
throw err;
};
return {
get: (...args) => base.get(...args).then(checkToken, mapAuthError),
post: (...args) => base.post(...args).then(checkToken, mapAuthError),
put: (...args) => base.put(...args).then(checkToken, mapAuthError),
delete: (...args) => base.delete(...args).then(checkToken, mapAuthError),
// Atlassian sunset the old `GET /rest/api/2/search` on Cloud only (410 Gone) in
// favor of `/search/jql`, which keeps the same v2 field shapes. Server/DC is on
// its own release cycle: the classic endpoint stays supported there, and an
// older DC version may not even serve `/search/jql` yet — so route on instance
// type instead of hardcoding one path. Every JQL search goes through here.
search: (params) => base.get(isCloud ? '/rest/api/2/search/jql' : '/rest/api/2/search', { params }).then(checkToken, mapAuthError)
};
}
/**
* Test JIRA instance connection
*/
export async function testConnection(instanceId) {
const config = await getInstances();
const instance = config.instances[instanceId];
if (!instance) {
throw instanceNotFound(instanceId);
}
const client = createJiraClient(instance);
try {
// Test with /rest/api/2/myself endpoint
const response = await client.get('/rest/api/2/myself');
return {
success: true,
user: response.data.displayName,
email: response.data.emailAddress
};
} catch (error) {
return {
success: false,
error: error.response?.data?.message || error.message
};
}
}
/**
* Get projects for JIRA instance
*/
export async function getProjects(instanceId) {
const config = await getInstances();
const instance = config.instances[instanceId];
if (!instance) {
throw instanceNotFound(instanceId);
}
const client = createJiraClient(instance);
const response = await client.get('/rest/api/2/project');
return response.data.map(project => ({
key: project.key,
name: project.name,
id: project.id
}));
}
/**
* Resolve a literal Cloud assignee to the GDPR-compatible accountId field.
*
* Jira's user search accepts both email addresses and display names. Keep the
* query's original spelling for Jira, but normalize the cache key so harmless
* casing differences do not create another request. A null result is reported
* but deliberately not cached, so an unresolvable configured value creates an
* unassigned ticket and can resolve on a later retry without sending the
* rejected `{ name }` shape to Cloud.
*/
async function resolveCloudAssignee(instanceId, client, assignee) {
const query = assignee.trim();
if (!query) return null;
const cacheKey = query.toLowerCase();
const instanceCache = getCloudAssigneeCache(instanceId);
const cachedAccountId = instanceCache.get(cacheKey);
if (cachedAccountId !== undefined) return cachedAccountId;
const lookup = cloudAssigneeLookupFlight.run(`${instanceId}\u0000${cacheKey}`, async () => {
const response = await client.get('/rest/api/2/user/search', { params: { query } });
if (!Array.isArray(response.data)) throw new Error('JIRA Cloud assignee search returned an invalid user list');
const users = response.data.filter(user => {
const accountType = typeof user?.accountType === 'string' ? user.accountType.toLowerCase() : null;
return user?.active !== false && accountType !== 'app';
});
const exactAccountIds = [...new Set(users
.filter(user => [user?.accountId, user?.emailAddress, user?.displayName, user?.name]
.some(value => typeof value === 'string' && value.trim().toLowerCase() === cacheKey))
.map(user => user?.accountId)
.filter(accountId => typeof accountId === 'string' && accountId.trim())
.map(accountId => accountId.trim()))];
const soleAccountId = response.data.length === 1 && users.length === 1 && typeof users[0]?.accountId === 'string'
? users[0].accountId.trim()
: '';
const accountId = exactAccountIds.length === 1
? exactAccountIds[0]
: exactAccountIds.length > 1
? null
: soleAccountId
? soleAccountId
: null;
if (accountId && cloudAssigneeCache.get(instanceId) === instanceCache) {
instanceCache.set(cacheKey, accountId);
}
if (!accountId) {
console.warn(`⚠️ JIRA Cloud assignee could not be resolved for instance ${instanceId}; creating ticket unassigned`);
}
return accountId;
});
return lookup.then(
accountId => accountId,
() => {
console.warn(`⚠️ JIRA Cloud assignee lookup failed for instance ${instanceId}; creating ticket unassigned`);
return null;
}
);
}
/**
* Look up one configured instance, or throw.
*
* The `getInstances() → lookup → throw` preamble is copy-pasted at ~20 call
* sites in this file. New and edited code goes through here; the rest migrate as
* they are touched, rather than in one mechanical sweep.
*/
async function resolveInstance(instanceId) {
const config = await getInstances();
const instance = config.instances[instanceId];
if (!instance) {
throw instanceNotFound(instanceId);
}
return instance;
}
/**
* Custom-field IDs vary per JIRA instance, so every read AND write of one goes
* through here. Shared by createTicket (which writes the epic link),
* getIssue/getEpicChildren (which read it back), and fetchMyCurrentSprintTickets
* (story points), so a claim agent resolving an epic's parent reads the exact
* field the creator wrote — a one-sided default would silently answer null.
*
* There is deliberately no `sprint` entry: sprint membership is set through the
* Agile API (see addIssuesToSprint), never by writing a custom field, so a
* `customFields.sprint` id would be config nothing reads.
*/
export function resolveCustomFieldIds(instance) {
return {
storyPoints: instance?.customFields?.storyPoints || 'customfield_10106',
epic: instance?.customFields?.epic || 'customfield_10101',
};
}
/**
* Resolve the authenticated JIRA account. Cloud identifies a user by `accountId`
* (GDPR retired `name`/`key`); Server/DC still uses `name`. Returned raw so
* callers can pick the field their endpoint expects.
*/
export async function getMyself(instanceId) {
const instance = await resolveInstance(instanceId);
const client = createJiraClient(instance);
const response = await client.get('/rest/api/2/myself');
const me = response.data || {};
return {
accountId: me.accountId || null,
name: me.name || null,
displayName: me.displayName || null,
emailAddress: me.emailAddress || null,
isCloud: isCloudInstance(instance.baseUrl)
};
}
// `assignee: 'currentUser'` is the sentinel a claim agent uses to make a filed
// child ticket claimable: the sprint query is `assignee = currentUser()`, and an
// agent has no way to know its own accountId up front.
const CURRENT_USER_ASSIGNEE = 'currentuser';
// The account behind an instance's credential does not change while the process
// runs, and the epic-decomposition flow files a whole batch of slices in a loop —
// without this, every one of them pays its own `/myself` round-trip. `undefined`
// means "not looked up"; a cached `null` means "looked up, no usable identity",
// so a resolvable-to-nothing instance is not re-probed on every create.
const currentUserFieldCache = new Map();
// Exported for tests and for a credential swap: `upsertInstance` can change which
// account a token authenticates as, which is the one thing the cache above can't see.
export function clearCurrentUserCache(instanceId) {
if (instanceId === undefined) currentUserFieldCache.clear();
else currentUserFieldCache.delete(instanceId);
}
/**
* Build the `fields.assignee` value for a create. Returns null when there is
* nothing to set.
*
* The `currentUser` sentinel resolves the caller's own identity and writes the
* field its instance type actually accepts: Cloud identifies a user by
* `accountId` (GDPR retired `name`), Server/DC by `name`. A LITERAL identifier
* goes through `resolveCloudAssignee` on Cloud — Cloud rejects a bare `{ name }`
* for the same GDPR reason — and is passed through as `{ name }` unchanged on
* Server/DC, which still accepts it.
*/
async function resolveAssigneeField(instanceId, instance, client, assignee) {
if (!assignee) return null;
// A caller that already built the JIRA object (`{ accountId }` / `{ name }`)
// gets it back untouched — stringifying it would write `{ name: "[object Object]" }`.
if (typeof assignee !== 'string') return assignee;
const trimmed = assignee.trim();
if (!trimmed) return null;
if (trimmed.toLowerCase() !== CURRENT_USER_ASSIGNEE) {
if (isCloudInstance(instance.baseUrl)) {
const accountId = await resolveCloudAssignee(instanceId, client, trimmed);
return accountId ? { accountId } : null;
}
return { name: trimmed };
}
const cached = currentUserFieldCache.get(instanceId);
if (cached !== undefined) return cached;
const me = await getMyself(instanceId);
const field = me.isCloud ? 'accountId' : 'name';
const resolved = me[field] ? { [field]: me[field] } : null;
currentUserFieldCache.set(instanceId, resolved);
return resolved;
}
// The two ways a project can express "this issue belongs to that epic". Only one
// exists on any given project — writing the wrong one is a 400, not a silent
// no-op — so a create tries the classic custom field first (what every install
// has been writing until now) and retries with the native `parent` field.
const EPIC_LINK_CUSTOM_FIELD = 'customField';
const EPIC_LINK_PARENT = 'parent';
/**
* Translate PortOS's domain ticket keys into the JIRA `fields` they actually
* name. Shared by createTicket and updateTicket: `jiraTicketUpdateSchema` is
* `jiraTicketCreateSchema.partial()`, so PUT accepts the same keys — and before
* this, forwarded `epicKey` / `storyPoints` / `assignee` verbatim, none of which
* is a JIRA field name. That wrote nothing and reported success.
*
* Only keys the caller actually supplied are mapped; everything else is left to
* the caller, so an update can still pass raw JIRA fields straight through.
*/
async function buildIssueFields(instanceId, instance, client, data, epicLinkAs = EPIC_LINK_CUSTOM_FIELD) {
const fieldIds = resolveCustomFieldIds(instance);
const fields = {};
if (data.summary !== undefined) fields.summary = data.summary;
// `!= null`, not truthiness — `storyPoints: 0` is a real estimate, and dropping
// it while answering 200 is the absent-vs-empty conflation AGENTS.md warns about.
if (data.storyPoints != null) fields[fieldIds.storyPoints] = data.storyPoints;
// The epic link has two incompatible spellings and only one exists per project
// (see getEpicChildren). `epicLinkAs` picks which to write; the caller retries
// with the other when the first is rejected.
if (data.epicKey) {
if (epicLinkAs === EPIC_LINK_PARENT) fields.parent = { key: data.epicKey };
else fields[fieldIds.epic] = data.epicKey;
}
// `issuetype` IS writable on update — JIRA accepts a type change on an existing
// issue — so it is mapped here rather than treated as a create-only concern.
if (data.issueType) fields.issuetype = { name: data.issueType };
// Array.isArray, not `.length` truthiness: `labels: []` is an intentional CLEAR
// and must reach JIRA, while an absent key must leave the existing labels alone.
if (Array.isArray(data.labels)) fields.labels = data.labels;
const assignee = await resolveAssigneeField(instanceId, instance, client, data.assignee);
if (assignee) fields.assignee = assignee;
return fields;
}
/**
* Move existing issues into a sprint via the Agile API.
*
* This is the only reliable way to sprint an issue: setting the sprint custom
* field on create is rejected outright on most Cloud instances ("Field cannot be
* set"), which is why `createTicket`'s old `fields[sprint]` write was both dead
* (it read `ticketData.sprint`, a key nothing sends) and wrong. Filing a child
* that never lands in the sprint strands it — the next claim run's candidate
* query only sees sprinted tickets.
*/
export async function addIssuesToSprint(instanceId, sprintId, issueKeys = []) {
const instance = await resolveInstance(instanceId);
const keys = issueKeys.filter(key => typeof key === 'string' && key.trim());
if (keys.length === 0) return { success: true, sprintId, issueKeys: [] };
const client = createJiraClient(instance);
await client.post(`/rest/agile/1.0/sprint/${encodeURIComponent(sprintId)}/issue`, { issues: keys });
return { success: true, sprintId, issueKeys: keys };
}
/**
* Create JIRA ticket.
*
* Returns `{ success, ticketId, url, sprint, response }`. `sprint` is the
* explicit sentinel for the sprint move: `null` when none was requested, else
* `{ id, assigned, error }` — `assigned: false` with an `error` means the ticket
* EXISTS but is not in the sprint, which a caller must surface rather than treat
* as a clean create (an unsprinted child is invisible to the next claim run).
*/
export async function createTicket(instanceId, ticketData) {
const instance = await resolveInstance(instanceId);
const client = createJiraClient(instance);
const buildIssue = async (epicLinkAs) => ({
fields: {
project: {
key: ticketData.projectKey
},
description: ticketData.description || ticketData.summary,
issuetype: {
name: ticketData.issueType || 'Task'
},
...(await buildIssueFields(instanceId, instance, client, ticketData, epicLinkAs))
}
});
// A project has exactly one epic-link spelling and rejects the other with a 400
// naming the offending field, so retry once with the alternative rather than
// filing an UNPARENTED child — a slice that isn't linked to its epic is
// invisible to the next run's child lookup and the decomposition strands.
const response = await client.post('/rest/api/2/issue', await buildIssue(EPIC_LINK_CUSTOM_FIELD))
.catch(async err => {
if (!ticketData.epicKey || err?.status !== 400) throw err;
console.warn(`⚠️ JIRA rejected the epic-link custom field, retrying ${ticketData.projectKey} create with parent`);
return client.post('/rest/api/2/issue', await buildIssue(EPIC_LINK_PARENT));
});
const ticketId = response.data.key;
const ticketUrl = `${instance.baseUrl}/browse/${ticketId}`;
// Sprint the ticket AFTER creation (see addIssuesToSprint). A failure here is
// reported, never thrown: the ticket already exists, so throwing would lose the
// key the caller needs to recover.
const sprintId = ticketData.sprintId ?? null;
let sprint = null;
if (sprintId !== null && sprintId !== '') {
sprint = await addIssuesToSprint(instanceId, sprintId, [ticketId])
.then(() => ({ id: sprintId, assigned: true, error: null }))
.catch(err => {
console.warn(`⚠️ JIRA ${ticketId} created but not added to sprint ${sprintId}: ${err.message}`);
return { id: sprintId, assigned: false, error: err.message };
});
}
return {
success: true,
ticketId,
url: ticketUrl,
sprint,
response: response.data
};
}
/**
* Search JIRA issues by an arbitrary JQL string. STRICT variant — lets fetch
* errors bubble so a caller can distinguish a transient API failure from a
* legitimately empty result set (the AGENTS.md sentinel rule). `fields` selects
* the returned issue fields; `maxResults` caps the page.
*
* Returns `[{ key, summary, description, status, statusCategory, priority,
* issueType, assignee, labels, updated, resolutiondate, url }]`.
*/
export async function searchIssues(instanceId, jql, { fields = 'summary,status,labels,updated,description,resolutiondate', maxResults = 100 } = {}) {
const config = await getInstances();
const instance = config.instances[instanceId];
if (!instance) {
throw instanceNotFound(instanceId);
}
const client = createJiraClient(instance);
const response = await client.search({ jql, fields, maxResults });
return (response.data.issues || []).map(issue => ({
key: issue.key,
summary: issue.fields.summary || '',
description: issue.fields.description || '',
status: issue.fields.status?.name || null,
statusCategory: issue.fields.status?.statusCategory?.name || null,
// Only populated when the caller asked for these fields (none is in the
// default `fields` set) — null otherwise, never a fabricated default.
priority: issue.fields.priority?.name || null,
issueType: issue.fields.issuetype?.name || null,
assignee: issue.fields.assignee?.displayName || issue.fields.assignee?.name || null,
labels: issue.fields.labels || [],
updated: issue.fields.updated || null,
resolutiondate: issue.fields.resolutiondate || null,
url: `${instance.baseUrl}/browse/${issue.key}`
}));
}
/**
* Add labels to an existing JIRA ticket without disturbing its other labels.
* Jira's field-update API takes an `update.labels` array of `{ add: <label> }`
* ops, so this is additive (unlike PUT-ing `fields.labels`, which replaces).
*/
export async function addLabels(instanceId, ticketId, labels = []) {
const config = await getInstances();
const instance = config.instances[instanceId];
if (!instance) {
throw instanceNotFound(instanceId);
}
const toAdd = (Array.isArray(labels) ? labels : []).filter(l => typeof l === 'string' && l.trim());
if (toAdd.length === 0) return { success: true, ticketId };
const client = createJiraClient(instance);
await client.put(`/rest/api/2/issue/${encodeURIComponent(ticketId)}`, {
update: { labels: toAdd.map(name => ({ add: name })) }
});
return { success: true, ticketId };
}
/**
* Update JIRA ticket
*/
export async function updateTicket(instanceId, ticketId, updates) {
const instance = await resolveInstance(instanceId);
const client = createJiraClient(instance);
// The domain keys go through the shared mapper so a PUT writes the same JIRA
// fields a POST does; anything else the caller sent is a raw JIRA field and is
// passed through untouched. `projectKey` and `sprintId` name nothing writable
// on an update — the route schema no longer accepts them, and sprint membership
// moves via addIssuesToSprint rather than a field write.
const { projectKey, sprintId, summary, issueType, storyPoints, epicKey, labels, assignee, ...rest } = updates;
const payload = {
fields: {
...rest,
...(await buildIssueFields(instanceId, instance, client, { summary, issueType, storyPoints, epicKey, labels, assignee }))
}
};
await client.put(`/rest/api/2/issue/${encodeURIComponent(ticketId)}`, payload);
return {
success: true,
ticketId,
url: `${instance.baseUrl}/browse/${ticketId}`
};
}
/**
* Add comment to JIRA ticket
*/
export async function addComment(instanceId, ticketId, comment) {
const config = await getInstances();
const instance = config.instances[instanceId];
if (!instance) {
throw instanceNotFound(instanceId);
}
const client = createJiraClient(instance);
await client.post(`/rest/api/2/issue/${encodeURIComponent(ticketId)}/comment`, {
body: comment
});
return { success: true };
}
/**
* Get available transitions for a JIRA ticket
*/
export async function getTransitions(instanceId, ticketId) {
const config = await getInstances();
const instance = config.instances[instanceId];
if (!instance) {
throw instanceNotFound(instanceId);
}
const client = createJiraClient(instance);
const response = await client.get(`/rest/api/2/issue/${encodeURIComponent(ticketId)}/transitions`);
return response.data.transitions.map(t => ({
id: t.id,
name: t.name,
to: t.to?.name,
toCategory: t.to?.statusCategory?.name
}));
}
/**
* Transition JIRA ticket (change status)
*/
export async function transitionTicket(instanceId, ticketId, transitionId) {
const config = await getInstances();
const instance = config.instances[instanceId];
if (!instance) {
throw instanceNotFound(instanceId);
}
const client = createJiraClient(instance);
await client.post(`/rest/api/2/issue/${encodeURIComponent(ticketId)}/transitions`, {
transition: { id: transitionId }
});
return { success: true };
}
/**
* Fetch tickets assigned to the current user in the active sprint for a project —
* STRICT variant that lets fetch errors bubble. Used by the issue-reconcile JIRA
* gatherer, which must distinguish a transient API failure (skip, don't park) from
* a legitimately empty sprint ([], a valid answer) — the sentinel rule in AGENTS.md.
* The UI-facing `getMyCurrentSprintTickets` wraps this and swallows to [] instead.
*/
export async function fetchMyCurrentSprintTickets(instanceId, projectKey) {
const instance = await resolveInstance(instanceId);
const client = createJiraClient(instance);
const fieldIds = resolveCustomFieldIds(instance);
// JQL to find tickets assigned to current user in active sprint for the project
const jql = `project = "${escapeJql(projectKey)}" AND assignee = currentUser() AND sprint in openSprints() ORDER BY priority DESC, updated DESC`;
// `labels` is what lets the claim flow see per-ticket markers (the `decomposed`
// epic marker, dispatch hints) without a second round-trip per candidate.
const response = await client.search({
jql,
fields: `summary,status,priority,issuetype,assignee,labels,updated,${fieldIds.storyPoints}`,
maxResults: 50
});
return response.data.issues.map(issue => ({
key: issue.key,
summary: issue.fields.summary,
status: issue.fields.status.name,
statusCategory: issue.fields.status.statusCategory?.name,
priority: issue.fields.priority?.name,
issueType: issue.fields.issuetype?.name,
labels: issue.fields.labels || [],
storyPoints: issue.fields[fieldIds.storyPoints],
updated: issue.fields.updated,
url: `${instance.baseUrl}/browse/${issue.key}`
}));
}
/**
* Get tickets assigned to user in current sprint for a project.
* Swallows fetch errors to [] so a JIRA blip never breaks the Kanban UI.
*/
export async function getMyCurrentSprintTickets(instanceId, projectKey) {
try {
return await fetchMyCurrentSprintTickets(instanceId, projectKey);
} catch (error) {
console.warn(`⚠️ JIRA sprint fetch failed for project ${projectKey}: ${error.message}`);
// Return empty array on error to avoid breaking the UI
return [];
}
}
// Canonical lifecycle ordering for the three Jira status categories. Used to
// order the fallback (no-board) column list — board-config columns keep their
// own configured order instead.
const CATEGORY_ORDER = { 'To Do': 0, 'In Progress': 1, 'Done': 2 };
/**
* Pure: turn an agile board's column config into Kanban columns.
* @param {Array} boardColumns - `columnConfig.columns` from the board config API
* (`[{ name, statuses: [{ id }] }]`).
* @param {Map<string,{name,category}>} statusById - status id → name/category.
* Returns ordered `[{ name, category, statuses: [statusName] }]`, dropping any
* column that maps to no known status (e.g. an empty/backlog column).
*/
export function buildColumnsFromBoardConfig(boardColumns, statusById) {
return (boardColumns || [])
.map(col => {
const statuses = (col.statuses || [])
.map(s => statusById.get(String(s.id)))
.filter(Boolean);
return {
name: col.name,
category: statuses[0]?.category || 'In Progress',
statuses: statuses.map(s => s.name)
};
})
.filter(col => col.statuses.length > 0);
}
/**
* Pure: turn a project's distinct workflow statuses into one column per status,
* ordered by status category (To Do → In Progress → Done). Used when no board
* id is available. `statusOrder` preserves discovery order so statuses within a
* category keep a stable layout (Array.prototype.sort is stable).
*/
export function buildColumnsFromStatuses(statusOrder) {
return (statusOrder || [])
.map(s => ({ name: s.name, category: s.category, statuses: [s.name] }))
.sort((a, b) => (CATEGORY_ORDER[a.category] ?? 1) - (CATEGORY_ORDER[b.category] ?? 1));
}
/**
* Resolve the ordered workflow columns for a project's board so the Kanban UI
* can show the full lifecycle (Blocked, In Review, any custom stage) instead of
* collapsing every status into the three statusCategory buckets.
*
* With a boardId we use the agile board's actual column layout — the truest
* representation of the user's workflow, in board order — mapping each column's
* status ids to names via the project statuses endpoint. Without a boardId, or
* if the board config can't be read, we fall back to the project's distinct
* statuses ordered by category. If even the project statuses can't be read the
* caller (client) falls back to its built-in three-category board.
*
* Returns `{ columns: [{ name, category, statuses: [statusName] }], source }`.
*/
export async function getBoardColumns(instanceId, projectKey, boardId) {
const config = await getInstances();
const instance = config.instances[instanceId];
if (!instance) {
throw instanceNotFound(instanceId);
}
const client = createJiraClient(instance);
// Project statuses (always) and the board config (only when we have a board)
// are independent calls — fetch them in parallel to save a round-trip. A
// board-config failure falls through to project-status columns (null).
const [statusesRes, boardColumns] = await Promise.all([
client.get(`/rest/api/2/project/${encodeURIComponent(projectKey)}/statuses`),
boardId
? client
.get(`/rest/agile/1.0/board/${encodeURIComponent(boardId)}/configuration`)
.then(res => res.data?.columnConfig?.columns || [])
.catch(err => {
console.warn(`⚠️ JIRA board ${boardId} config fetch failed: ${err.message}`);
return null;
})
: Promise.resolve(null)
]);
// status id → { name, category }, plus discovery order for the fallback.
const statusById = new Map();
const statusOrder = [];
for (const issueType of statusesRes.data || []) {
for (const s of issueType.statuses || []) {
const id = String(s.id);
if (!statusById.has(id)) {
const entry = { name: s.name, category: s.statusCategory?.name || 'To Do' };
statusById.set(id, entry);
statusOrder.push(entry);
}
}
}
if (boardColumns) {
const columns = buildColumnsFromBoardConfig(boardColumns, statusById);
if (columns.length > 0) {
return { columns, source: 'board' };
}
}
return { columns: buildColumnsFromStatuses(statusOrder), source: 'project' };
}
/**
* Get active sprints for a JIRA board
*/
export async function getActiveSprints(instanceId, boardId) {
const config = await getInstances();
const instance = config.instances[instanceId];
if (!instance) {
throw instanceNotFound(instanceId);
}
const client = createJiraClient(instance);
const response = await client.get(`/rest/agile/1.0/board/${encodeURIComponent(boardId)}/sprint`, {
params: { state: 'active' }
});
return response.data.values.map(sprint => ({
id: sprint.id,
name: sprint.name,
state: sprint.state,
startDate: sprint.startDate,
endDate: sprint.endDate
}));
}
/**
* Search for epics in a JIRA project by name
*/
export async function searchEpics(instanceId, projectKey, query) {
const config = await getInstances();
const instance = config.instances[instanceId];
if (!instance) {
throw instanceNotFound(instanceId);
}
const client = createJiraClient(instance);
const safeProject = escapeJql(projectKey);
const safeQuery = escapeJql(query);
const jql = `project = "${safeProject}" AND issuetype = Epic AND summary ~ "${safeQuery}" ORDER BY updated DESC`;
const response = await client.search({
jql,
fields: 'summary,status',
maxResults: 10
});
return response.data.issues.map(issue => ({
key: issue.key,
summary: issue.fields.summary,
status: issue.fields.status.name
}));
}
/**
* List agile boards for a JIRA project (Scrum + Kanban).
* Powers the app-config "detect boards" picker so a boardId is chosen from live
* data instead of hand-typed — which is how a boardId goes stale across a
* Server→Cloud migration (the id is reassigned). The Agile board list paginates,
* so walk every page until isLast.
*/
export async function getBoards(instanceId, projectKey) {
const config = await getInstances();
const instance = config.instances[instanceId];
if (!instance) {
throw instanceNotFound(instanceId);
}
const client = createJiraClient(instance);
const boards = [];
let startAt = 0;
let guard = 0;
for (;;) {
const response = await client.get('/rest/agile/1.0/board', {
params: { projectKeyOrId: projectKey, maxResults: 50, startAt }
});
const values = response.data.values || [];
for (const b of values) {
boards.push({
id: b.id,
name: b.name,
type: b.type,
projectKey: b.location?.projectKey || null
});
}
// isLast is authoritative; the empty-page and guard checks are belt-and-suspenders
// so a misbehaving API can't spin this loop forever.
if (response.data.isLast || values.length === 0 || ++guard > 40) break;
startAt += values.length;
}
return boards;
}
/**
* Fetch a single issue by key.
*
* Used by the app-config picker to validate that a configured epicKey still
* resolves on the instance (keys can vanish/change across a migration), and by
* the claim flow's epic decomposition, which needs three things the original
* summary/type/status projection did not carry: `labels` (to see the
* `decomposed` marker), `description` (to append and re-read the
* "Decomposed into" checklist), and `epicKey` (to walk a child back to its
* parent). Throws (bubbles to a 4xx) when the key doesn't resolve — the caller
* treats that as "no longer resolves".
*
* `epicKey` reads BOTH the instance's configured epic-link custom field and the
* native `parent` field: company-managed projects use the custom field, while
* team-managed (next-gen) projects only ever populate `parent`.
*/
export async function getIssue(instanceId, issueKey) {
const instance = await resolveInstance(instanceId);
const fieldIds = resolveCustomFieldIds(instance);
const client = createJiraClient(instance);
const response = await client.get(`/rest/api/2/issue/${encodeURIComponent(issueKey)}`, {
params: { fields: `summary,status,issuetype,labels,description,parent,${fieldIds.epic}` }
});
const fields = response.data.fields || {};
const epicLink = fields[fieldIds.epic];
return {
key: response.data.key,
summary: fields.summary || '',
status: fields.status?.name || null,
issueType: fields.issuetype?.name || null,
labels: fields.labels || [],
// Absent stays null, never '' — an empty description is a legitimate value a
// caller must be able to tell apart from a field the projection didn't carry.
description: typeof fields.description === 'string' ? fields.description : null,
// The custom field holds a bare key string; `parent` holds an issue object.
epicKey: (typeof epicLink === 'string' ? epicLink : epicLink?.key) || fields.parent?.key || null
};
}
/**
* List the child issues of an epic.
*
* JIRA has two incompatible epic-link models and no way to know up front which
* one a project uses: `parent` (team-managed, and the modern Cloud spelling) and
* the instance's configured epic-link custom field via `cf[...]` (company-managed,
* classic). A single `OR` query is not an option — a project that lacks either
* field rejects the WHOLE query with a 400 — so both run separately and their
* results are unioned by key.
*
* Both must run even when the first one succeeds. `parent` is valid JQL on
* Server/DC as the long-standing sub-task clause, so a company-managed project
* whose children hang off the Epic Link field answers it with a clean, empty 200
* rather than a 400. Returning that empty result would report an already-split
* epic as childless, and the claim flow would re-split it into duplicate slices.
*
* A 400 means only "this project does not know that clause" and is tolerated;
* anything else (401/403/5xx/network) bubbles immediately, because "the lookup
* failed" must never collapse into "the epic has no children". An empty union
* after every clause succeeded IS a genuinely childless epic.
*/
export async function getEpicChildren(instanceId, epicKey, { maxResults = 100 } = {}) {
const instance = await resolveInstance(instanceId);
const fieldIds = resolveCustomFieldIds(instance);
const epicFieldNumber = String(fieldIds.epic).replace(/^customfield_/, '');
const safeKey = escapeJql(epicKey);
const clauses = [
`parent = "${safeKey}"`,
`cf[${epicFieldNumber}] = "${safeKey}"`
];
const byKey = new Map();
let rejected = 0;
let lastError = null;
for (const clause of clauses) {
const issues = await searchIssues(
instanceId,
`${clause} ORDER BY created ASC`,
{ fields: 'summary,status,labels,issuetype,assignee,updated', maxResults }
).catch(err => {
if (err?.status !== 400) throw err;
rejected += 1;
lastError = err;
return null;
});
if (issues === null) continue;
for (const issue of issues) {
if (!byKey.has(issue.key)) byKey.set(issue.key, issue);
}
}
// Every clause was rejected as bad JQL — that is a failed lookup, not an
// answer, so it must throw rather than report zero children.
if (rejected === clauses.length) throw lastError;
return [...byKey.values()];
}
export default {
getInstances,
saveInstances,
upsertInstance,
deleteInstance,
clearCloudAssigneeCache,
testConnection,
getProjects,
getBoards,
getIssue,
getEpicChildren,
getMyself,
resolveCustomFieldIds,
clearCurrentUserCache,
createTicket,
addIssuesToSprint,
searchIssues,
addLabels,
updateTicket,
addComment,
getTransitions,
transitionTicket,
getMyCurrentSprintTickets,
fetchMyCurrentSprintTickets,
getBoardColumns,
buildColumnsFromBoardConfig,
buildColumnsFromStatuses,
getActiveSprints,
searchEpics
};