light-plan 0.0.0-stage → 0.1.0

package/dist/remote/providers/jira/index.js

@@ -0,0 +1,100 @@
+/**
+ * The Jira provider adapter — one folder, exposing the four-member `Provider`
+ * shape the registry holds.
+ *
+ * Adding a provider is exactly this folder plus one line in
+ * `src/remote/registry.ts`. Nothing in core or the planners names Jira.
+ */
+import { jiraConfigSchema } from './config.js';
+import { jiraConnector } from './connector.js';
+import { jiraTranslator } from './translator.js';
+import { jiraVocabulary } from './vocabulary.js';
+export { jiraDependsOnOf, jiraRelatesToOf } from './links.js';
+export { jiraParentIdOf, jiraNativeParentIdOf } from './hierarchy.js';
+/**
+ * The remote id a Jira record is keyed by: its numeric issue `id`, the same id
+ * the connector writes into a `ConnectorResult.remoteId`. The human-facing
+ * `key` (`PAY-418`) is never used as a key — it is carried as `remoteKey`.
+ */
+export function jiraRemoteIdOf(record) {
+    const id = record['id'];
+    if (typeof id === 'string' && id !== '')
+        return id;
+    if (typeof id === 'number')
+        return String(id);
+    return '';
+}
+/**
+ * Jira Cloud's capability table (LP-274), from the LP-267 audit
+ * (`docs/remote-capabilities.md`). Static cells are facts of the platform;
+ * probed cells vary by plan or permission and are answered by
+ * `jiraConnector(...).probe(name)` once per remote.
+ *
+ * Jira is the *most* capable platform of the three researched: native types,
+ * transition-mediated statuses, native blocking/relates edges, rich custom
+ * fields, sprints and full-featured comments.
+ */
+export const jiraCapabilities = {
+    // Epic → Story → Sub-task is the *classic* ceiling, but levels above Epic
+    // are a paid Premium feature and the ceiling is per-project configuration —
+    // so the depth is detected against the project's actual type scheme, never
+    // assumed (LP-324). The connector answers the `hierarchy` probe once per
+    // remote.
+    hierarchyDepth: { probe: 'hierarchy' },
+    // Jira's hierarchy is defined from the bottom up — `Subtask` < standard <
+    // `Epic` — and only a standard issue may sit under an Epic. So the native
+    // chain is spent on the *deepest* board levels: the work items nest under
+    // their container, and everything above rides the managed block. Anchored at
+    // the root instead, every native edge lands where Jira refuses it (a board
+    // with three levels above its stories maps them all onto `Epic`, and an Epic
+    // may not sit under an Epic) while the one relationship Jira would hold is
+    // the one that degrades — which is how a filed board came out flat.
+    hierarchyAnchor: 'leaf',
+    // Issue types are native and per-project.
+    nativeTypes: true,
+    // Status is a workflow: a change is a transition, and the target may be
+    // unreachable from where the issue stands.
+    status: { kind: 'transitions' },
+    // `blocks` / `is blocked by` and `relates to` are native issue links.
+    edges: { dependsOn: true, relatesTo: true },
+    // Custom fields exist extensively; the value types available are a live fact
+    // (LP-324 discovers and caches names → ids against the instance).
+    customFields: { probe: 'custom_fields' },
+    // Custom fields and sprints are creatable; labels are free-form (applied,
+    // never pre-created).
+    provisioning: { customFields: true, periods: true, labels: false },
+    // Sprints are native period containers, creatable through the Agile API.
+    periods: { native: true, creatable: true },
+    // Comments carry ids, can be edited and deleted.
+    comments: { native: true, editable: true, deletable: true },
+    // Cursor-paginated search (`nextPageToken`) paired with a `updated >=` JQL
+    // filter — the offset-paginated endpoint is deprecated and never used.
+    incrementalRead: { kind: 'cursor' },
+    // Issue types and workflow statuses are the project's own vocabulary.
+    vocabulary: 'fixed',
+};
+export const jiraProvider = {
+    config: jiraConfigSchema,
+    capabilities: jiraCapabilities,
+    translator: jiraTranslator,
+    connector: jiraConnector,
+    conditionalConnection: [
+        {
+            key: 'board',
+            needs: 'periods',
+            why: 'a Jira sprint belongs to an Agile board, not a project. ' +
+                'Run `lpm remote setup jira` to find it, or set it by hand: the id is the number in the ' +
+                'board URL (…/jira/software/c/projects/PAY/boards/12).',
+        },
+    ],
+    credentials: {
+        secrets: { email: 'JIRA_EMAIL', token: 'JIRA_API_TOKEN' },
+        visible: ['email'],
+        url: 'https://id.atlassian.com/manage-profile/security/api-tokens',
+        hint: 'An Atlassian API token, plus the email of the account that owns it. What the token may ' +
+            'do is decided by the project permissions that account has (Browse / Create / Edit / ' +
+            'Transition Issues at a minimum) — see docs/remote-jira.md for the list to send an admin.',
+    },
+    standardVocabulary: jiraVocabulary,
+};
+//# sourceMappingURL=index.js.map

package/dist/remote/providers/jira/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/remote/providers/jira/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAEtE;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,MAAoB;IACjD,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IACxB,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,EAAE,CAAC;IACnD,IAAI,OAAO,EAAE,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,EAAE,CAAC,CAAC;IAC9C,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAiB;IAC5C,0EAA0E;IAC1E,4EAA4E;IAC5E,2EAA2E;IAC3E,yEAAyE;IACzE,UAAU;IACV,cAAc,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE;IACtC,0EAA0E;IAC1E,0EAA0E;IAC1E,0EAA0E;IAC1E,6EAA6E;IAC7E,2EAA2E;IAC3E,6EAA6E;IAC7E,2EAA2E;IAC3E,oEAAoE;IACpE,eAAe,EAAE,MAAM;IACvB,0CAA0C;IAC1C,WAAW,EAAE,IAAI;IACjB,wEAAwE;IACxE,2CAA2C;IAC3C,MAAM,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE;IAC/B,sEAAsE;IACtE,KAAK,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE;IAC3C,6EAA6E;IAC7E,kEAAkE;IAClE,YAAY,EAAE,EAAE,KAAK,EAAE,eAAe,EAAE;IACxC,0EAA0E;IAC1E,sBAAsB;IACtB,YAAY,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE;IAClE,yEAAyE;IACzE,OAAO,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE;IAC1C,iDAAiD;IACjD,QAAQ,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE;IAC3D,2EAA2E;IAC3E,uEAAuE;IACvE,eAAe,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;IACnC,sEAAsE;IACtE,UAAU,EAAE,OAAO;CACpB,CAAC;AAEF,MAAM,CAAC,MAAM,YAAY,GAAa;IACpC,MAAM,EAAE,gBAAgB;IACxB,YAAY,EAAE,gBAAgB;IAC9B,UAAU,EAAE,cAAc;IAC1B,SAAS,EAAE,aAAa;IACxB,qBAAqB,EAAE;QACrB;YACE,GAAG,EAAE,OAAO;YACZ,KAAK,EAAE,SAAS;YAChB,GAAG,EACD,0DAA0D;gBAC1D,yFAAyF;gBACzF,uDAAuD;SAC1D;KACF;IACD,WAAW,EAAE;QACX,OAAO,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,gBAAgB,EAAE;QACzD,OAAO,EAAE,CAAC,OAAO,CAAC;QAClB,GAAG,EAAE,6DAA6D;QAClE,IAAI,EACF,yFAAyF;YACzF,sFAAsF;YACtF,0FAA0F;KAC7F;IACD,kBAAkB,EAAE,cAAc;CACnC,CAAC"}

package/dist/remote/providers/jira/links.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Jira's native issue-link read seams (LP-325): `depends_on` and `relates_to`
+ * recovered from the `issuelinks` field a Jira record carries.
+ *
+ * **An issue's `issuelinks` entry names only the *other* end.** This is the
+ * thing to get right, and it was got wrong: an entry carries `inwardIssue`
+ * *or* `outwardIssue`, never both, and the key says what the other issue is
+ * relative to this one. So there is no "is this end me?" test to make — the
+ * record is always the end that is missing — and code that compared the
+ * record against both endpoints matched nothing at all, which is why every
+ * dependency read back from a live Jira came out empty.
+ *
+ * What the keys mean, measured against Jira Cloud rather than read off the
+ * field names (they invite the opposite reading):
+ *
+ *   - `depends_on` → the `Blocks` link type. An entry carrying
+ *     `inwardIssue: Y` reads "this issue **is blocked by** Y", so Y is a
+ *     dependency of the record. An entry carrying `outwardIssue: Y` reads
+ *     "this issue **blocks** Y" — the same edge seen from the other side, and
+ *     nothing this record waits on.
+ *   - `relates_to` → the `Relates` link type, symmetric. Either key holds the
+ *     other side, and both mean the same thing.
+ *
+ * The returned values are **remote ids** (the numeric issue id the link store
+ * keys by), resolved by the pull planner exactly like a native sub-issue
+ * parent — through the link store, or through the pending-create map when the
+ * other endpoint is pulled in the same run.
+ *
+ * Pure: no I/O.
+ */
+import type { RemoteRecord } from '../../provider.js';
+/**
+ * The remote ids of the issues `record` waits on: the outward ("blocks") issue
+ * of every `Blocks` link the record is inward ("is blocked by") of.
+ */
+export declare function jiraDependsOnOf(record: RemoteRecord): string[];
+/**
+ * The remote ids of the issues `record` relates to: the other side of every
+ * `Relates` link, whichever orientation the record sits on.
+ */
+export declare function jiraRelatesToOf(record: RemoteRecord): string[];

package/dist/remote/providers/jira/links.js

@@ -0,0 +1,102 @@
+/**
+ * Jira's native issue-link read seams (LP-325): `depends_on` and `relates_to`
+ * recovered from the `issuelinks` field a Jira record carries.
+ *
+ * **An issue's `issuelinks` entry names only the *other* end.** This is the
+ * thing to get right, and it was got wrong: an entry carries `inwardIssue`
+ * *or* `outwardIssue`, never both, and the key says what the other issue is
+ * relative to this one. So there is no "is this end me?" test to make — the
+ * record is always the end that is missing — and code that compared the
+ * record against both endpoints matched nothing at all, which is why every
+ * dependency read back from a live Jira came out empty.
+ *
+ * What the keys mean, measured against Jira Cloud rather than read off the
+ * field names (they invite the opposite reading):
+ *
+ *   - `depends_on` → the `Blocks` link type. An entry carrying
+ *     `inwardIssue: Y` reads "this issue **is blocked by** Y", so Y is a
+ *     dependency of the record. An entry carrying `outwardIssue: Y` reads
+ *     "this issue **blocks** Y" — the same edge seen from the other side, and
+ *     nothing this record waits on.
+ *   - `relates_to` → the `Relates` link type, symmetric. Either key holds the
+ *     other side, and both mean the same thing.
+ *
+ * The returned values are **remote ids** (the numeric issue id the link store
+ * keys by), resolved by the pull planner exactly like a native sub-issue
+ * parent — through the link store, or through the pending-create map when the
+ * other endpoint is pulled in the same run.
+ *
+ * Pure: no I/O.
+ */
+/** The `issuelinks` entries a record carries, or an empty list. */
+function issueLinksOf(record) {
+    const fields = record['fields'];
+    if (!fields || typeof fields !== 'object' || Array.isArray(fields))
+        return [];
+    const links = fields['issuelinks'];
+    if (!Array.isArray(links))
+        return [];
+    return links.filter((link) => link !== null && typeof link === 'object');
+}
+/** The name of a link's type (`Blocks`, `Relates`), or ''. */
+function typeNameOf(link) {
+    const type = link['type'];
+    if (!type || typeof type !== 'object')
+        return '';
+    const name = type['name'];
+    return typeof name === 'string' ? name : '';
+}
+/** An endpoint's id and key, each empty when absent. */
+function endpointOf(value) {
+    if (!value || typeof value !== 'object')
+        return { id: '', key: '' };
+    const record = value;
+    const id = record['id'];
+    const key = record['key'];
+    return {
+        id: typeof id === 'string' ? id : typeof id === 'number' ? String(id) : '',
+        key: typeof key === 'string' ? key : '',
+    };
+}
+/** A remote id from an endpoint, preferring the numeric id the link store keys by. */
+function remoteIdOf(endpoint) {
+    return endpoint.id !== '' ? endpoint.id : endpoint.key;
+}
+/**
+ * The remote ids of the issues `record` waits on: the outward ("blocks") issue
+ * of every `Blocks` link the record is inward ("is blocked by") of.
+ */
+export function jiraDependsOnOf(record) {
+    const ids = [];
+    for (const link of issueLinksOf(record)) {
+        if (typeNameOf(link) !== 'Blocks')
+            continue;
+        // `inwardIssue` present = "this issue is blocked by that one", which is
+        // exactly a dependency. An `outwardIssue` entry is the reverse edge and
+        // belongs to the other issue's list, not this one's.
+        if (link['inwardIssue'] === undefined)
+            continue;
+        const id = remoteIdOf(endpointOf(link['inwardIssue']));
+        if (id !== '')
+            ids.push(id);
+    }
+    return [...new Set(ids)].sort();
+}
+/**
+ * The remote ids of the issues `record` relates to: the other side of every
+ * `Relates` link, whichever orientation the record sits on.
+ */
+export function jiraRelatesToOf(record) {
+    const ids = [];
+    for (const link of issueLinksOf(record)) {
+        if (typeNameOf(link) !== 'Relates')
+            continue;
+        // Symmetric, so whichever key holds the other end is the target.
+        const other = link['inwardIssue'] !== undefined ? link['inwardIssue'] : link['outwardIssue'];
+        const id = remoteIdOf(endpointOf(other));
+        if (id !== '')
+            ids.push(id);
+    }
+    return [...new Set(ids)].sort();
+}
+//# sourceMappingURL=links.js.map

package/dist/remote/providers/jira/links.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"links.js","sourceRoot":"","sources":["../../../../src/remote/providers/jira/links.ts"],"names":[],"mappings":"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"}

package/dist/remote/providers/jira/sprints.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Jira sprints (LP-328) — the period container, pure half.
+ *
+ * Jira's native period container is a **sprint**, and sprints belong to an
+ * *Agile board*, not a project — so reading and writing them goes through the
+ * Agile API (`/rest/agile/1.0/…`), a separate base path from the v3 issue API.
+ * This module is the pure part: the sprint model, the page parser, the name
+ * lookup and the two facts that gate a write (a closed sprint refuses work, a
+ * missing sprint is a provision request rather than a silent no-op).
+ *
+ * The network half lives in `connector.ts` (`sprints()`, `createSprint`, the
+ * sprint field read/write on create/update/get/list). The translator's period
+ * push/pull uses `PeriodContainer` / `mapPeriodFromRemote` from
+ * `../../periods.ts` exactly as GitHub's milestone carrier does — the sprint
+ * carrier is a third `PeriodCarrier`, and the join is by sprint *name*.
+ */
+import type { JiraField } from './fields.js';
+/** One sprint as the Agile API returns it (`GET /board/{boardId}/sprint`). */
+export interface JiraSprint {
+    /** The sprint's numeric id, e.g. `37`. */
+    id: string;
+    /** The sprint name, e.g. "Sprint 1" — what a period title matches. */
+    name: string;
+    /** The sprint state: `future`, `active` or `closed`. */
+    state: string;
+    /** `startDate`, `YYYY-MM-DD`, when the sprint carries one. */
+    starts?: string;
+    /** `endDate`, `YYYY-MM-DD`, when the sprint carries one. */
+    ends?: string;
+    /** `completeDate`, an ISO timestamp, when the sprint was closed. */
+    completeDate?: string;
+}
+/**
+ * The custom-field *type key* that identifies Jira's built-in sprint field.
+ * The field's per-instance id (`customfield_10020`) is discovered from the
+ * instance's field list, never hard-coded — exactly as `mapping.attributes`
+ * resolves names to ids (LP-327).
+ */
+export declare const SPRINT_FIELD_TYPE = "com.pyxis.greenhopper.jira:gh-sprint";
+/**
+ * Parse one Agile API sprint page (`{ values: [...], isLast, startAt }`) into
+ * `JiraSprint`s. The board sprint endpoint returns sprints in every state —
+ * future, active and closed — which is what lets a push tell a closed sprint
+ * from a future one before moving work into it. Dates arrive as strings from
+ * the wire but as `Date`s after jira.js validates them, so both spellings are
+ * read.
+ */
+export declare function parseSprints(raw: unknown): JiraSprint[];
+/** True when the sprint is `closed` — the one state work must never move into. */
+export declare function isClosedSprint(sprint: JiraSprint): boolean;
+/** The sprint whose name matches, or `undefined` when the board has none. */
+export declare function sprintByName(sprints: readonly JiraSprint[], name: string): JiraSprint | undefined;
+/** The desired sprints that have no match among the board's existing sprints,
+ * in board order — what a push creates before it files. Idempotent by
+ * construction: re-running against an updated sprint list creates nothing. */
+export declare function missingSprints(desired: readonly {
+    name: string;
+    starts?: string;
+    ends?: string;
+}[], existing: readonly JiraSprint[]): Array<{
+    name: string;
+    starts?: string;
+    ends?: string;
+}>;
+/** The sprint custom field's per-instance id, or `undefined` when the instance
+ * has no sprint field (which is itself the honest answer for "sprints are not
+ * enabled here"). */
+export declare function sprintFieldIdOf(fields: readonly Pick<JiraField, 'id' | 'customType'>[]): string | undefined;
+/** The sprint operations the live Jira connector exposes, for `lpm remote
+ * provision` and the translator's push/pull. Absent on a fake that does not
+ * model sprints. */
+export interface JiraSprintConnector {
+    readonly name: string;
+    /** Every sprint on the configured Agile board, in every state. */
+    listSprints?(signal?: AbortSignal): Promise<JiraSprint[]>;
+    /** Create a future sprint on the configured Agile board, returning its id. */
+    createSprint?(name: string, starts?: string, ends?: string, signal?: AbortSignal): Promise<{
+        id: string;
+    }>;
+}

package/dist/remote/providers/jira/sprints.js

@@ -0,0 +1,107 @@
+/**
+ * Jira sprints (LP-328) — the period container, pure half.
+ *
+ * Jira's native period container is a **sprint**, and sprints belong to an
+ * *Agile board*, not a project — so reading and writing them goes through the
+ * Agile API (`/rest/agile/1.0/…`), a separate base path from the v3 issue API.
+ * This module is the pure part: the sprint model, the page parser, the name
+ * lookup and the two facts that gate a write (a closed sprint refuses work, a
+ * missing sprint is a provision request rather than a silent no-op).
+ *
+ * The network half lives in `connector.ts` (`sprints()`, `createSprint`, the
+ * sprint field read/write on create/update/get/list). The translator's period
+ * push/pull uses `PeriodContainer` / `mapPeriodFromRemote` from
+ * `../../periods.ts` exactly as GitHub's milestone carrier does — the sprint
+ * carrier is a third `PeriodCarrier`, and the join is by sprint *name*.
+ */
+/**
+ * The custom-field *type key* that identifies Jira's built-in sprint field.
+ * The field's per-instance id (`customfield_10020`) is discovered from the
+ * instance's field list, never hard-coded — exactly as `mapping.attributes`
+ * resolves names to ids (LP-327).
+ */
+export const SPRINT_FIELD_TYPE = 'com.pyxis.greenhopper.jira:gh-sprint';
+// ---------------------------------------------------------------------------
+// Parsing
+// ---------------------------------------------------------------------------
+/** A sprint date as `YYYY-MM-DD`, from a string or a Date the client coerced. */
+function dateOnly(value) {
+    if (typeof value === 'string')
+        return value;
+    if (value instanceof Date && !Number.isNaN(value.getTime())) {
+        return value.toISOString().slice(0, 10);
+    }
+    return undefined;
+}
+/** A sprint timestamp as an ISO string, from a string or a Date the client coerced. */
+function timestampOf(value) {
+    if (typeof value === 'string')
+        return value;
+    if (value instanceof Date && !Number.isNaN(value.getTime()))
+        return value.toISOString();
+    return undefined;
+}
+/**
+ * Parse one Agile API sprint page (`{ values: [...], isLast, startAt }`) into
+ * `JiraSprint`s. The board sprint endpoint returns sprints in every state —
+ * future, active and closed — which is what lets a push tell a closed sprint
+ * from a future one before moving work into it. Dates arrive as strings from
+ * the wire but as `Date`s after jira.js validates them, so both spellings are
+ * read.
+ */
+export function parseSprints(raw) {
+    if (raw === null || typeof raw !== 'object')
+        return [];
+    const record = raw;
+    const values = record['values'];
+    if (!Array.isArray(values))
+        return [];
+    const out = [];
+    for (const entry of values) {
+        if (entry === null || typeof entry !== 'object')
+            continue;
+        const sprint = entry;
+        const id = sprint['id'];
+        const name = sprint['name'];
+        if ((typeof id !== 'string' && typeof id !== 'number') || typeof name !== 'string')
+            continue;
+        const state = sprint['state'];
+        out.push({
+            id: String(id),
+            name,
+            state: typeof state === 'string' ? state : '',
+            ...(dateOnly(sprint['startDate']) !== undefined ? { starts: dateOnly(sprint['startDate']) } : {}),
+            ...(dateOnly(sprint['endDate']) !== undefined ? { ends: dateOnly(sprint['endDate']) } : {}),
+            ...(timestampOf(sprint['completeDate']) !== undefined
+                ? { completeDate: timestampOf(sprint['completeDate']) }
+                : {}),
+        });
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// The two facts a write needs
+// ---------------------------------------------------------------------------
+/** True when the sprint is `closed` — the one state work must never move into. */
+export function isClosedSprint(sprint) {
+    return sprint.state.trim().toLowerCase() === 'closed';
+}
+/** The sprint whose name matches, or `undefined` when the board has none. */
+export function sprintByName(sprints, name) {
+    return sprints.find((sprint) => sprint.name === name);
+}
+/** The desired sprints that have no match among the board's existing sprints,
+ * in board order — what a push creates before it files. Idempotent by
+ * construction: re-running against an updated sprint list creates nothing. */
+export function missingSprints(desired, existing) {
+    const names = new Set(existing.map((sprint) => sprint.name));
+    return desired.filter((entry) => !names.has(entry.name));
+}
+/** The sprint custom field's per-instance id, or `undefined` when the instance
+ * has no sprint field (which is itself the honest answer for "sprints are not
+ * enabled here"). */
+export function sprintFieldIdOf(fields) {
+    const field = fields.find((entry) => entry.customType === SPRINT_FIELD_TYPE);
+    return field?.id;
+}
+//# sourceMappingURL=sprints.js.map

package/dist/remote/providers/jira/sprints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sprints.js","sourceRoot":"","sources":["../../../../src/remote/providers/jira/sprints.ts"],"names":[],"mappings":"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"}

package/dist/remote/providers/jira/translator.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Jira's two-way vocabulary translation.
+ *
+ * Jira Cloud has *native* issue types, workflow statuses and custom fields, so
+ * the mapping names them rather than encoding them onto labels (the GitHub
+ * approach). This translator is the Jira-specific bridge, using the remote's
+ * `mapping` block:
+ *
+ *   push: a `BoardOp` plus the mapping becomes a `RemoteRequest` carrying
+ *         `type` (issuetype name), `state` (workflow status name, transition-
+ *         mediated), `title`, `body`, `assignee` and `parent` key;
+ *   pull: a Jira issue record plus the mapping becomes a `BoardFieldsPatch`,
+ *         recovering `type` from `fields.issuetype.name` and `status` from
+ *         `fields.status.name` when the mapping names them unambiguously.
+ *
+ * Pure: no I/O. One translator serves every Jira remote. Where a value cannot
+ * be mapped back unambiguously, the field is left absent rather than guessed —
+ * the pull planner breaks ties with the board's hierarchy (LP-268).
+ *
+ * Two things are deliberately deferred rather than half-encoded here:
+ * **custom fields** (LP-324) — `mapping.attributes` names a field id, but
+ * `RemoteRequest` has no field to carry it, so attributes are deferred until
+ * that wire shape exists. **Sprints** (LP-328) are carried natively: the
+ * period resolves to a `PeriodContainer` on push and the connector writes the
+ * sprint field, and on pull the connector's `record.sprint` enrichment resolves
+ * back to a period by name.
+ */
+import type { AttributeDefs } from '../../provider.js';
+import type { BoardOp, DescribeResult, FieldsFromRecordResult, RemoteRecord, Translator } from '../../provider.js';
+import { type Roster } from '../../accounts.js';
+import { type PeriodIndex } from '../../periods.js';
+/**
+ * Recover the local markdown body from a Jira `description` field.
+ *
+ * Jira Cloud returns `description` as an ADF document (an object) — never a
+ * markdown string — so this is where ADF → markdown happens. It also accepts
+ * the defensive spellings: a client that stringified the ADF, and a plain
+ * string left by an older write, both degrade gracefully rather than dropping
+ * the prose.
+ */
+export declare function bodyFromDescription(description: unknown): string | undefined;
+/**
+ * Push: a board op becomes a Jira request description.
+ *
+ * `type` is the mapped issuetype name; `state` the mapped workflow status name
+ * (a push writes it as a transition, resolved by the connector). A create/update
+ * also carries `title`, `body` and the resolved assignee account id. A delete
+ * carries only its kind — Jira deletes hard.
+ */
+export declare function describeRequest(op: BoardOp, mapping: Record<string, unknown>, _attributes: AttributeDefs, roster?: Roster, periods?: PeriodIndex): DescribeResult;
+/**
+ * Pull: a Jira issue record becomes board fields.
+ *
+ * `title` ← `fields.summary`; `body` ← `fields.description` (a string here —
+ * Jira Cloud returns ADF, and LP-322 is where the ADF → markdown conversion
+ * lands); `type` ← `fields.issuetype.name` matched against the mapping's
+ * native type names; `status` ← `fields.status.name`; `assignee` ← the account
+ * id matched against the roster.
+ */
+export declare function fieldsFromRecord(record: RemoteRecord, mapping: Record<string, unknown>, _attributes: AttributeDefs, roster?: Roster, periods?: PeriodIndex): FieldsFromRecordResult;
+export declare const jiraTranslator: Translator;