specrails-desktop 2.3.0 → 2.4.0

package/server/dist/jira/jira-issue-fields.js

@@ -0,0 +1,428 @@
+"use strict";
+// Pure, I/O-free renderer for the read-only "Jira details" panel: turns a raw
+// issue field map (fields=*all) + /field metadata into an ordered list of
+// populated, non-skipped { label, value, href? } rows. Also normalizes the
+// dev-status (PR/branch/commit) payloads. NEVER throws — bad shapes are dropped.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SKIP_SYSTEM_FIELDS = void 0;
+exports.indexFieldMeta = indexFieldMeta;
+exports.resolveCustomFieldId = resolveCustomFieldId;
+exports.humanizeKey = humanizeKey;
+exports.formatIssueFields = formatIssueFields;
+exports.normalizePullRequests = normalizePullRequests;
+exports.normalizeBranches = normalizeBranches;
+exports.normalizeRepositoryCommits = normalizeRepositoryCommits;
+const jira_adf_1 = require("./jira-adf");
+const jira_materializer_1 = require("./jira-materializer");
+/** System fields the modal already shows OR that are noise — never rendered. */
+exports.SKIP_SYSTEM_FIELDS = new Set([
+    // already shown by the modal / card
+    'summary', 'description', 'status', 'priority', 'labels', 'assignee',
+    // identity / housekeeping
+    'project', 'key', 'id', 'self', 'expand', 'thumbnail', 'lastViewed',
+    'statuscategorychangedate', 'workratio', 'issuerestriction', 'issuekey',
+    // aggregates / progress (covered by timetracking)
+    'aggregatetimespent', 'aggregatetimeestimate', 'aggregatetimeoriginalestimate',
+    'aggregateprogress', 'progress', 'timeoriginalestimate', 'timeestimate', 'timespent',
+    // heavy / out-of-scope content blocks
+    'comment', 'worklog', 'attachment',
+    // footer already shows local created/updated
+    'created', 'updated',
+]);
+// Custom-field schema.custom suffixes we recognise (never hardcode customfield_NNN).
+const STORY_POINTS = [':float', ':jsw-story-points', ':story-point-estimate'];
+const EPIC_LINK = 'com.pyxis.greenhopper.jira:gh-epic-link';
+const EPIC_NAME = 'com.pyxis.greenhopper.jira:gh-epic-label';
+const FLAGGED = [':gh-jira-flag', ':greenhopper-flagged-field'];
+const TEAM = [':atlassian-team', ':rm-teams-custom-field-team'];
+const SPRINT = 'com.pyxis.greenhopper.jira:gh-sprint';
+const RANK = [':gh-lexo-rank', ':lexorank'];
+/**
+ * Custom-field schema.custom substrings whose VALUE is an internal serialized
+ * blob (not human content) — must never render as a "field". The Development
+ * summary field is the prime case: its branches/PRs/commits are surfaced in the
+ * dedicated Development section via the dev-status API, not as a raw blob row.
+ */
+const SKIP_CUSTOM_SCHEMA = [
+    'jira-development-integration-plugin', // Development summary (devsummary / devsummarycf)
+    ':devsummary',
+    ':global-rank',
+    ':aozoraplugin', // misc internal aggregates seen on some instances
+];
+function isSkippedCustomSchema(custom) {
+    return !!custom && SKIP_CUSTOM_SCHEMA.some((s) => custom.includes(s));
+}
+/** A populated string value that is actually a serialized object/map blob. */
+function looksLikeSerializedBlob(value) {
+    return /^\s*[{[]/.test(value);
+}
+function indexFieldMeta(meta) {
+    const m = new Map();
+    for (const f of meta)
+        if (f && typeof f.id === 'string')
+            m.set(f.id, f);
+    return m;
+}
+/** Resolve a custom field id by schema.custom suffix OR exact name. null when absent. */
+function resolveCustomFieldId(meta, opts) {
+    const names = (opts.names ?? []).map((n) => n.toLowerCase());
+    for (const f of meta.values()) {
+        const custom = f.schema?.custom;
+        if (custom && (opts.customEndsWith ?? []).some((s) => custom.endsWith(s) || custom === s))
+            return f.id;
+        if (f.name && names.includes(f.name.toLowerCase()))
+            return f.id;
+    }
+    return null;
+}
+function isPlainObject(v) {
+    return !!v && typeof v === 'object' && !Array.isArray(v);
+}
+/** Title-case a field key for the label fallback when /field metadata is missing. */
+function humanizeKey(key) {
+    const spaced = key.replace(/([a-z])([A-Z])/g, '$1 $2').replace(/[_-]+/g, ' ').trim();
+    return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}
+const ISSUE_KEY_RE = /^[A-Z][A-Z0-9]+-\d+$/;
+/** Render a scalar/object value by schema, or by shape when schema is absent. Returns
+ *  the display string, or null when the value is empty/unpopulated. */
+function scalarDisplay(raw, schemaType) {
+    if (raw == null)
+        return null;
+    switch (schemaType) {
+        case 'user':
+            return userName(raw);
+        case 'priority':
+        case 'status':
+        case 'resolution':
+        case 'issuetype':
+        case 'securitylevel':
+        case 'component':
+        case 'version':
+            return isPlainObject(raw) ? str(raw.name) : null;
+        case 'option':
+        case 'option-with-child': {
+            if (!isPlainObject(raw))
+                return null;
+            const base = str(raw.value) ?? str(raw.name);
+            const child = isPlainObject(raw.child) ? str(raw.child.value) ?? str(raw.child.name) : null;
+            return base ? (child ? `${base} / ${child}` : base) : null;
+        }
+        case 'votes':
+            return isPlainObject(raw) && typeof raw.votes === 'number' && raw.votes > 0 ? String(raw.votes) : null;
+        case 'watches':
+            return isPlainObject(raw) && typeof raw.watchCount === 'number' && raw.watchCount > 0 ? String(raw.watchCount) : null;
+        case 'timetracking':
+            return timetracking(raw);
+        case 'number':
+            return typeof raw === 'number' ? String(raw) : null;
+        case 'date':
+        case 'datetime':
+            return typeof raw === 'string' && raw.trim() ? raw : null;
+        case 'string':
+            return text(raw);
+        default:
+            return sniff(raw);
+    }
+}
+/** Shape-sniff a value with no usable schema (covers many custom fields). */
+function sniff(raw) {
+    if (typeof raw === 'string')
+        return text(raw);
+    if (typeof raw === 'number')
+        return String(raw);
+    if (typeof raw === 'boolean')
+        return raw ? 'Yes' : null;
+    if (Array.isArray(raw)) {
+        const parts = raw.map((x) => sniff(x)).filter((x) => !!x);
+        return parts.length ? parts.join(', ') : null;
+    }
+    if (isPlainObject(raw)) {
+        return str(raw.value) ?? str(raw.name) ?? str(raw.displayName) ?? userName(raw);
+    }
+    return null;
+}
+function userName(raw) {
+    if (!isPlainObject(raw))
+        return null;
+    return str(raw.displayName) ?? str(raw.emailAddress) ?? str(raw.name);
+}
+function text(raw) {
+    if (typeof raw !== 'string') {
+        // ADF rich text (e.g. environment on Cloud).
+        if (isPlainObject(raw) && raw.type === 'doc') {
+            const t = (0, jira_adf_1.adfToText)(raw).trim();
+            return t || null;
+        }
+        return null;
+    }
+    const t = raw.trim();
+    return t || null;
+}
+function str(v) {
+    return typeof v === 'string' && v.trim() ? v.trim() : null;
+}
+function timetracking(raw) {
+    if (!isPlainObject(raw))
+        return null;
+    const lines = [];
+    if (str(raw.originalEstimate))
+        lines.push(`Original: ${raw.originalEstimate}`);
+    if (str(raw.remainingEstimate))
+        lines.push(`Remaining: ${raw.remainingEstimate}`);
+    if (str(raw.timeSpent))
+        lines.push(`Spent: ${raw.timeSpent}`);
+    return lines.length ? lines.join('\n') : null;
+}
+function arrayDisplay(raw, itemType) {
+    if (raw.length === 0)
+        return null;
+    let parts;
+    switch (itemType) {
+        case 'string':
+            parts = raw.filter((x) => typeof x === 'string' && x.trim().length > 0);
+            break;
+        case 'user':
+            parts = raw.map(userName).filter((x) => !!x);
+            break;
+        case 'component':
+        case 'version':
+            parts = raw.map((x) => (isPlainObject(x) ? str(x.name) : null)).filter((x) => !!x);
+            break;
+        case 'option':
+            parts = raw.map((x) => (isPlainObject(x) ? str(x.value) ?? str(x.name) : null)).filter((x) => !!x);
+            break;
+        default:
+            parts = raw.map((x) => sniff(x)).filter((x) => !!x);
+    }
+    return parts.length ? parts.join(', ') : null;
+}
+function labelFor(key, ctx) {
+    return ctx.meta.get(key)?.name ?? humanizeKey(key);
+}
+/** PURE. Ordered, populated, non-skipped detail rows for the read-only panel. */
+function formatIssueFields(input) {
+    const f = input.fields ?? {};
+    const ctx = { meta: indexFieldMeta(input.fieldMeta ?? []), baseUrl: input.baseUrl };
+    const rows = [];
+    const handled = new Set();
+    const push = (key, schemaType, opts) => {
+        handled.add(key);
+        const value = scalarDisplay(f[key], schemaType);
+        if (value != null)
+            rows.push({ label: opts?.label ?? labelFor(key, ctx), value });
+    };
+    const pushArray = (key, itemType, opts) => {
+        handled.add(key);
+        const v = f[key];
+        if (!Array.isArray(v))
+            return;
+        const value = arrayDisplay(v, itemType);
+        if (value != null)
+            rows.push({ label: opts?.label ?? labelFor(key, ctx), value });
+    };
+    // ── Ordered system fields ──────────────────────────────────────────────────
+    push('issuetype', 'issuetype');
+    push('resolution', 'resolution');
+    push('reporter', 'user');
+    // creator: suppress when identical to reporter.
+    handled.add('creator');
+    {
+        const creator = userName(f.creator);
+        const reporter = userName(f.reporter);
+        if (creator && creator !== reporter)
+            rows.push({ label: labelFor('creator', ctx), value: creator });
+    }
+    pushArray('components', 'component');
+    pushArray('fixVersions', 'version');
+    pushArray('versions', 'version');
+    push('environment', 'string');
+    // parent: only when it is NOT an epic (epic parent is shown as jira_epic_key).
+    handled.add('parent');
+    {
+        const p = f.parent;
+        if (isPlainObject(p)) {
+            const itype = isPlainObject(p.fields) && isPlainObject(p.fields.issuetype) ? str(p.fields.issuetype.name) : null;
+            const key = str(p.key);
+            if (key && (itype ?? '').toLowerCase() !== 'epic') {
+                const summary = isPlainObject(p.fields) ? str(p.fields.summary) : null;
+                rows.push({ label: labelFor('parent', ctx), value: summary ? `${key} — ${summary}` : key, href: (0, jira_materializer_1.issueUrl)(ctx.baseUrl, key) });
+            }
+        }
+    }
+    // subtasks: headline count + one linked row each.
+    handled.add('subtasks');
+    if (Array.isArray(f.subtasks) && f.subtasks.length > 0) {
+        rows.push({ label: labelFor('subtasks', ctx), value: `${f.subtasks.length} sub-tasks` });
+        for (const s of f.subtasks) {
+            if (!isPlainObject(s))
+                continue;
+            const key = str(s.key);
+            if (!key)
+                continue;
+            const summary = isPlainObject(s.fields) ? str(s.fields.summary) : null;
+            rows.push({ label: key, value: summary ?? key, href: (0, jira_materializer_1.issueUrl)(ctx.baseUrl, key) });
+        }
+    }
+    // issuelinks: one row per linked issue, labelled by the relationship.
+    handled.add('issuelinks');
+    if (Array.isArray(f.issuelinks)) {
+        for (const link of f.issuelinks) {
+            if (!isPlainObject(link) || !isPlainObject(link.type))
+                continue;
+            const out = isPlainObject(link.outwardIssue) ? link.outwardIssue : null;
+            const inw = isPlainObject(link.inwardIssue) ? link.inwardIssue : null;
+            const rel = out ? str(link.type.outward) : str(link.type.inward);
+            const issue = out ?? inw;
+            if (!issue)
+                continue;
+            const key = str(issue.key);
+            if (!key)
+                continue;
+            const summary = isPlainObject(issue.fields) ? str(issue.fields.summary) : null;
+            rows.push({ label: rel ?? labelFor('issuelinks', ctx), value: summary ? `${key} — ${summary}` : key, href: (0, jira_materializer_1.issueUrl)(ctx.baseUrl, key) });
+        }
+    }
+    push('duedate', 'date');
+    push('resolutiondate', 'datetime');
+    push('security', 'securitylevel', { label: labelFor('security', ctx) });
+    push('votes', 'votes');
+    push('watches', 'watches');
+    push('timetracking', 'timetracking');
+    // ── Resolved custom fields ──────────────────────────────────────────────────
+    const sp = resolveCustomFieldId(ctx.meta, { customEndsWith: STORY_POINTS, names: ['Story Points', 'Story point estimate'] });
+    if (sp && typeof f[sp] === 'number') {
+        handled.add(sp);
+        rows.push({ label: ctx.meta.get(sp)?.name ?? 'Story Points', value: String(f[sp]) });
+    }
+    if (!input.alreadyShown.hasEpicKey) {
+        const el = resolveCustomFieldId(ctx.meta, { customEndsWith: [EPIC_LINK] });
+        if (el && str(f[el])) {
+            handled.add(el);
+            const key = str(f[el]);
+            rows.push({ label: ctx.meta.get(el)?.name ?? 'Epic Link', value: key, href: (0, jira_materializer_1.issueUrl)(ctx.baseUrl, key) });
+        }
+        const en = resolveCustomFieldId(ctx.meta, { customEndsWith: [EPIC_NAME] });
+        if (en && str(f[en])) {
+            handled.add(en);
+            rows.push({ label: ctx.meta.get(en)?.name ?? 'Epic Name', value: str(f[en]) });
+        }
+    }
+    const flag = resolveCustomFieldId(ctx.meta, { customEndsWith: FLAGGED, names: ['Flagged'] });
+    if (flag && Array.isArray(f[flag]) && f[flag].length > 0) {
+        handled.add(flag);
+        rows.push({ label: ctx.meta.get(flag)?.name ?? 'Flagged', value: 'Impediment' });
+    }
+    const team = resolveCustomFieldId(ctx.meta, { customEndsWith: TEAM, names: ['Team'] });
+    if (team) {
+        handled.add(team);
+        const v = f[team];
+        const name = isPlainObject(v) ? str(v.name) ?? str(v.title) ?? str(v.value) : str(v);
+        if (name)
+            rows.push({ label: ctx.meta.get(team)?.name ?? 'Team', value: name });
+    }
+    // Mark sprint + rank custom fields handled so the generic sweep skips them.
+    for (const id of [
+        resolveCustomFieldId(ctx.meta, { customEndsWith: [SPRINT] }),
+        resolveCustomFieldId(ctx.meta, { customEndsWith: RANK }),
+    ])
+        if (id)
+            handled.add(id);
+    // ── Generic sweep: any remaining populated custom field ─────────────────────
+    const sweep = [];
+    for (const key of Object.keys(f)) {
+        if (handled.has(key) || exports.SKIP_SYSTEM_FIELDS.has(key) || !key.startsWith('customfield_'))
+            continue;
+        const meta = ctx.meta.get(key);
+        const schema = meta?.schema;
+        // Skip internal serialized-blob custom fields (e.g. the Development summary —
+        // its PRs/branches/commits are surfaced in the Development section instead).
+        if (isSkippedCustomSchema(schema?.custom))
+            continue;
+        const value = Array.isArray(f[key]) ? arrayDisplay(f[key], schema?.items)
+            : scalarDisplay(f[key], schema?.type);
+        // Defensive: a value that is a serialized object/map blob is not human content.
+        if (value != null && !looksLikeSerializedBlob(value))
+            sweep.push({ label: labelFor(key, ctx), value });
+    }
+    sweep.sort((a, b) => a.label.localeCompare(b.label));
+    rows.push(...sweep);
+    return rows;
+}
+// ─── Development (dev-status) normalizers ──────────────────────────────────────
+function mapCommit(raw) {
+    if (!isPlainObject(raw))
+        return null;
+    const url = str(raw.url);
+    if (!url)
+        return null;
+    return {
+        id: str(raw.id) ?? '',
+        displayId: str(raw.displayId) ?? (str(raw.id) ?? '').slice(0, 7),
+        message: str(raw.message) ?? '',
+        url,
+        author: isPlainObject(raw.author) ? str(raw.author.name) : null,
+        timestamp: str(raw.authorTimestamp) ?? str(raw.timestamp) ?? null,
+    };
+}
+function normalizePullRequests(detail) {
+    const out = [];
+    for (const d of detail?.detail ?? []) {
+        for (const pr of (isPlainObject(d) && Array.isArray(d.pullRequests) ? d.pullRequests : [])) {
+            if (!isPlainObject(pr))
+                continue;
+            const url = str(pr.url);
+            if (!url)
+                continue;
+            out.push({
+                id: str(pr.id) ?? '',
+                title: str(pr.name) ?? str(pr.id) ?? '',
+                url,
+                status: str(pr.status) ?? 'UNKNOWN',
+                sourceBranch: isPlainObject(pr.source) ? str(pr.source.branch) : null,
+                destBranch: isPlainObject(pr.destination) ? str(pr.destination.branch) : null,
+                author: isPlainObject(pr.author) ? str(pr.author.name) : null,
+                lastUpdate: str(pr.lastUpdate) ?? null,
+            });
+        }
+    }
+    return out;
+}
+function normalizeBranches(detail) {
+    const out = [];
+    for (const d of detail?.detail ?? []) {
+        for (const b of (isPlainObject(d) && Array.isArray(d.branches) ? d.branches : [])) {
+            if (!isPlainObject(b))
+                continue;
+            const url = str(b.url);
+            if (!url)
+                continue;
+            out.push({
+                name: str(b.name) ?? '',
+                url,
+                createPullRequestUrl: str(b.createPullRequestUrl) ?? null,
+                repo: isPlainObject(b.repository) ? str(b.repository.name) : null,
+                repoUrl: isPlainObject(b.repository) ? str(b.repository.url) : null,
+                lastCommit: mapCommit(b.lastCommit),
+            });
+        }
+    }
+    return out;
+}
+function normalizeRepositoryCommits(detail) {
+    const out = [];
+    for (const d of detail?.detail ?? []) {
+        for (const repo of (isPlainObject(d) && Array.isArray(d.repositories) ? d.repositories : [])) {
+            if (!isPlainObject(repo) || !Array.isArray(repo.commits))
+                continue;
+            for (const c of repo.commits) {
+                const mapped = mapCommit(c);
+                if (mapped)
+                    out.push(mapped);
+                if (out.length >= 50)
+                    return out;
+            }
+        }
+    }
+    return out;
+}

package/server/dist/jira/jira-materializer.js

@@ -0,0 +1,250 @@
+"use strict";
+// Inbound materializer: Jira issues → `.specrails/local-tickets.json`.
+//
+// The local store stays the canonical read cache that specrails-core reads
+// unchanged. This module performs a SURGICAL merge (never a wholesale rewrite):
+// it only upserts tickets that have a Jira link and preserves every locally-
+// created ticket (no jira link) untouched. It also:
+//   - allocates Jira `#id`s from the UNION of the store's next_id and the
+//     jira_links max, so Jira ids never collide with local specs;
+//   - skips the `status` field for any ticket with a pending outbox op
+//     ("frozen" ids) so an inbound poll never reverts a status we just wrote.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.issueStatusCategory = issueStatusCategory;
+exports.mapStatus = mapStatus;
+exports.mapPriority = mapPriority;
+exports.issueUrl = issueUrl;
+exports.extractEpic = extractEpic;
+exports.extractSprint = extractSprint;
+exports.mapIssueToTicket = mapIssueToTicket;
+exports.upsertIssuesIntoStore = upsertIssuesIntoStore;
+const ticket_store_1 = require("../ticket-store");
+const jira_adf_1 = require("./jira-adf");
+const jira_db_1 = require("./jira-db");
+const CANCEL_NAMES = ['won\'t do', 'wont do', 'cancelled', 'canceled', 'rejected', 'abandoned', 'invalid', 'duplicate', 'declined'];
+function issueStatusCategory(issue) {
+    const k = issue.fields.status?.statusCategory?.key;
+    return k === 'new' || k === 'done' ? k : 'indeterminate';
+}
+/** Map a Jira issue's status to a Specrails ticket status. */
+function mapStatus(issue) {
+    const cat = issueStatusCategory(issue);
+    if (cat === 'new')
+        return 'todo';
+    if (cat === 'indeterminate')
+        return 'in_progress';
+    // done category: distinguish a cancelled/rejected resolution from a real ship.
+    const name = (issue.fields.status?.name ?? '').toLowerCase();
+    return CANCEL_NAMES.some((w) => name.includes(w)) ? 'cancelled' : 'done';
+}
+/** Map a Jira priority name to a Specrails priority (best-effort, defaults medium). */
+function mapPriority(name) {
+    switch ((name ?? '').toLowerCase()) {
+        case 'highest':
+        case 'blocker':
+        case 'critical':
+            return 'critical';
+        case 'high':
+            return 'high';
+        case 'low':
+        case 'lowest':
+        case 'trivial':
+        case 'minor':
+            return 'low';
+        default:
+            return 'medium';
+    }
+}
+/** Build the issue's browser URL from the base URL + key. */
+function issueUrl(baseUrl, key) {
+    return `${baseUrl.replace(/\/+$/, '')}/browse/${key}`;
+}
+/**
+ * Extract the parent epic from an issue. In modern Jira (company- and
+ * team-managed) the epic is the issue's `parent`. We only treat the parent as an
+ * epic when its issue type is Epic (when that info is present); otherwise we keep
+ * the parent reference anyway (most spec-issues' parent is the epic).
+ */
+function extractEpic(issue) {
+    const parent = issue.fields.parent;
+    if (!parent?.key)
+        return { key: null, name: null };
+    const typeName = parent.fields?.issuetype?.name;
+    if (typeName && typeName.toLowerCase() !== 'epic')
+        return { key: null, name: null };
+    return { key: parent.key, name: parent.fields?.summary ?? parent.key };
+}
+/**
+ * Extract the issue's sprint from the (instance-specific) sprint custom field.
+ * The value is an array of sprint objects `[{ id, name, state }]`; we prefer the
+ * ACTIVE sprint, else the last one listed (Jira orders past→future). Returns
+ * null/null when there's no sprint field or no sprint. Tolerant of the value
+ * being absent, a non-array, or legacy string entries.
+ */
+function extractSprint(issue, sprintFieldId) {
+    if (!sprintFieldId || sprintFieldId === 'none')
+        return { id: null, name: null, state: null };
+    const raw = issue.fields[sprintFieldId];
+    if (!Array.isArray(raw) || raw.length === 0)
+        return { id: null, name: null, state: null };
+    const objs = raw.filter((s) => !!s && typeof s === 'object');
+    if (objs.length === 0)
+        return { id: null, name: null, state: null };
+    const active = objs.find((s) => typeof s.state === 'string' && s.state.toLowerCase() === 'active');
+    const chosen = active ?? objs[objs.length - 1];
+    const id = chosen.id != null ? String(chosen.id) : null;
+    const name = typeof chosen.name === 'string' ? chosen.name : id;
+    const state = typeof chosen.state === 'string' ? chosen.state.toLowerCase() : null;
+    return { id, name, state };
+}
+/** Map a Jira issue to a full Ticket. `existing` preserves created_at and local-only fields. */
+function mapIssueToTicket(issue, localId, conn, existing) {
+    const now = new Date().toISOString();
+    const sprint = extractSprint(issue, conn.sprintFieldId);
+    return {
+        id: localId,
+        title: issue.fields.summary || `(${issue.key})`,
+        description: (0, jira_adf_1.adfToText)(issue.fields.description),
+        status: mapStatus(issue),
+        priority: mapPriority(issue.fields.priority?.name),
+        labels: issue.fields.labels ?? [],
+        assignee: issue.fields.assignee?.displayName ?? issue.fields.assignee?.emailAddress ?? null,
+        prerequisites: existing?.prerequisites ?? [],
+        metadata: existing?.metadata ?? {},
+        comments: existing?.comments ?? [],
+        attachments: existing?.attachments,
+        origin_conversation_id: existing?.origin_conversation_id ?? null,
+        is_epic: existing?.is_epic ?? false,
+        parent_epic_id: existing?.parent_epic_id ?? null,
+        execution_order: existing?.execution_order ?? null,
+        short_summary: existing?.short_summary ?? null,
+        created_at: existing?.created_at ?? now,
+        updated_at: now,
+        created_by: existing?.created_by ?? 'jira',
+        source: 'jira',
+        jira_key: issue.key,
+        jira_url: issueUrl(conn.baseUrl, issue.key),
+        jira_epic_key: extractEpic(issue).key,
+        jira_epic_name: extractEpic(issue).name,
+        jira_sprint_id: sprint.id,
+        jira_sprint_name: sprint.name,
+        jira_sprint_state: sprint.state,
+    };
+}
+/** Compare the Jira-derived content of two tickets, ignoring updated_at. */
+function sameJiraContent(a, b) {
+    return (a.title === b.title &&
+        a.description === b.description &&
+        a.status === b.status &&
+        a.priority === b.priority &&
+        a.assignee === b.assignee &&
+        (a.jira_key ?? null) === (b.jira_key ?? null) &&
+        (a.jira_url ?? null) === (b.jira_url ?? null) &&
+        (a.jira_epic_key ?? null) === (b.jira_epic_key ?? null) &&
+        (a.jira_epic_name ?? null) === (b.jira_epic_name ?? null) &&
+        (a.jira_sprint_id ?? null) === (b.jira_sprint_id ?? null) &&
+        (a.jira_sprint_name ?? null) === (b.jira_sprint_name ?? null) &&
+        (a.jira_sprint_state ?? null) === (b.jira_sprint_state ?? null) &&
+        a.labels.length === b.labels.length &&
+        a.labels.every((l, i) => l === b.labels[i]));
+}
+/**
+ * Apply the frozen-id guard to a freshly mapped ticket. A frozen id has a pending
+ * outbound write (a status transition OR a field write-back), so inbound Jira
+ * data must NOT clobber the locally-edited fields before that write lands — the
+ * poll would otherwise revert the user's edit. We preserve the editable fields
+ * (status/priority/title/description/labels) and let Jira-owned fields
+ * (key/url/epic/sprint/assignee) flow through.
+ */
+function applyFrozen(mapped, existing, frozen) {
+    if (existing && frozen) {
+        mapped.status = existing.status;
+        mapped.priority = existing.priority ?? mapped.priority;
+        mapped.title = existing.title;
+        mapped.description = existing.description;
+        mapped.labels = existing.labels;
+    }
+    return mapped;
+}
+/**
+ * Upsert a batch of Jira issues into the local store. `frozenLocalIds` is the set
+ * of local ids whose `status` must NOT be overwritten by inbound data (they have
+ * a pending outbox op or are on an active rail). Returns the changed local ids
+ * and the max Jira `updated` timestamp seen (drives the high-water mark — derived
+ * from Jira's own server timestamps, never the local clock).
+ */
+function upsertIssuesIntoStore(db, projectPath, conn, issues, frozenLocalIds = new Set()) {
+    const ticketFile = (0, ticket_store_1.resolveTicketStoragePath)(projectPath);
+    let maxUpdatedMs = conn.highWaterMs ?? 0;
+    // ── Pre-pass (no lock): decide whether ANYTHING actually changed ──────────
+    // The high-water + 2-min overlap means most polls return issues that are
+    // byte-identical to what we already cached. Writing the store anyway bumps its
+    // revision and makes the file-watcher fire a full-board refresh → the every-60s
+    // flicker. So when nothing changed we skip the write (and the broadcasts)
+    // entirely and return the unchanged revision.
+    const preStore = (0, ticket_store_1.readStore)(ticketFile);
+    let anyChange = false;
+    for (const issue of issues) {
+        const u = issue.fields.updated ? Date.parse(issue.fields.updated) : 0;
+        if (!Number.isNaN(u) && u > maxUpdatedMs)
+            maxUpdatedMs = u;
+        const link = (0, jira_db_1.getLinkByIssueId)(db, issue.id);
+        if (!link) {
+            anyChange = true;
+            continue;
+        }
+        if (issue.key && issue.key !== link.jiraKey) {
+            anyChange = true;
+            continue;
+        }
+        const existing = preStore.tickets[String(link.localId)];
+        if (!existing) {
+            anyChange = true;
+            continue;
+        }
+        const mapped = applyFrozen(mapIssueToTicket(issue, link.localId, conn, existing), existing, frozenLocalIds.has(link.localId));
+        if (!sameJiraContent(existing, mapped))
+            anyChange = true;
+    }
+    if (!anyChange) {
+        return { changedLocalIds: [], maxUpdatedMs, upserted: 0, revision: preStore.revision, wrote: false };
+    }
+    // ── Write pass (locked): persist only the tickets that actually changed ────
+    const changedLocalIds = [];
+    const store = (0, ticket_store_1.mutateStore)(ticketFile, (s) => {
+        for (const issue of issues) {
+            let link = (0, jira_db_1.getLinkByIssueId)(db, issue.id);
+            if (!link) {
+                const localId = Math.max(s.next_id, nextJiraLocalId(db));
+                link = (0, jira_db_1.insertLinkWithId)(db, {
+                    localId,
+                    jiraIssueId: issue.id,
+                    jiraKey: issue.key,
+                    jiraProjectId: conn.jiraProjectId,
+                    deployment: conn.deployment,
+                });
+                if (localId >= s.next_id)
+                    s.next_id = localId + 1;
+            }
+            else if (issue.key && issue.key !== link.jiraKey) {
+                // Issue moved/renamed — refresh the display key (link keyed on immutable id).
+                db.prepare('UPDATE jira_links SET jira_key = ?, updated_at = ? WHERE jira_issue_id = ?').run(issue.key, new Date().toISOString(), issue.id);
+            }
+            const localId = link.localId;
+            const existing = s.tickets[String(localId)];
+            const mapped = applyFrozen(mapIssueToTicket(issue, localId, conn, existing), existing, frozenLocalIds.has(localId));
+            // Unchanged tickets are left exactly as-is — no reassignment (keeps their
+            // updated_at) and no ticket_updated broadcast.
+            if (existing && sameJiraContent(existing, mapped))
+                continue;
+            s.tickets[String(localId)] = mapped;
+            changedLocalIds.push(localId);
+            (0, jira_db_1.updateLinkStatusCategory)(db, issue.id, issueStatusCategory(issue));
+        }
+    });
+    return { changedLocalIds, maxUpdatedMs, upserted: changedLocalIds.length, revision: store.revision, wrote: true };
+}
+function nextJiraLocalId(db) {
+    const row = db.prepare('SELECT MAX(local_id) AS maxId FROM jira_links').get();
+    return (row.maxId ?? 0) + 1;
+}