openplanr 1.2.8 → 1.3.0

package/dist/services/linear/body-formatters.js

@@ -0,0 +1,183 @@
+/**
+ * Pure markdown body/description formatters for Linear issues and projects.
+ *
+ * Every function here takes local OpenPlanr artifact data and returns the
+ * string that goes into the Linear entity's `description` / `title` field.
+ * Stateless + side-effect free except for `buildMergedTaskListBody`, which
+ * reads task files via the artifact-service to assemble a feature's
+ * aggregated checkbox body.
+ */
+import { parseTaskMarkdown } from '../../agents/task-parser.js';
+import { readArtifact, readArtifactRaw } from '../artifact-service.js';
+/** Convert an unknown frontmatter value to an optional string at the type boundary. */
+export function toOptionalString(v) {
+    return typeof v === 'string' ? v : undefined;
+}
+/** Convert an unknown frontmatter value to an optional array of strings. */
+export function toOptionalStringArray(v) {
+    if (!Array.isArray(v))
+        return undefined;
+    const out = v.filter((item) => typeof item === 'string');
+    return out.length > 0 ? out : undefined;
+}
+/** Epic → Linear Project `description` (markdown). Skips whitespace-only sections. */
+export function buildEpicProjectDescription(epic) {
+    const lines = [];
+    const section = (label, value) => {
+        const trimmed = value?.trim();
+        if (trimmed)
+            lines.push(`**${label}**\n\n${trimmed}`);
+    };
+    section('Business value', epic.businessValue);
+    section('Problem', epic.problemStatement);
+    section('Solution', epic.solutionOverview);
+    section('Success criteria', epic.successCriteria);
+    section('Target users', epic.targetUsers);
+    section('Risks', epic.risks);
+    section('Dependencies', epic.dependencies);
+    return lines.join('\n\n');
+}
+/** Feature → Linear issue body (overview + functional requirements bullets). */
+export function buildFeatureIssueBody(feature) {
+    const lines = [feature.overview?.trim() || ''];
+    if (feature.functionalRequirements?.length) {
+        lines.push('**Functional requirements**');
+        for (const r of feature.functionalRequirements) {
+            lines.push(`- ${r}`);
+        }
+    }
+    return lines.filter(Boolean).join('\n\n');
+}
+/**
+ * User story → Linear sub-issue body.
+ *
+ * Composes, in order:
+ *   1. The "As a / I want / So that" sentence — only when all three fields
+ *      are present (otherwise rendering with blanks produces visible
+ *      garbage in Linear).
+ *   2. The frontmatter `acceptanceCriteria` prose — if set.
+ *   3. The Gherkin scenarios from `<storyId>-gherkin.feature` — if the
+ *      caller provides them. Stories in the OpenPlanr convention store
+ *      their real acceptance criteria as Gherkin in a sibling `.feature`
+ *      file; without this, the Linear issue was empty for every story
+ *      that followed the convention.
+ */
+export function buildStoryIssueBody(story, gherkinContent) {
+    const role = story.role?.trim();
+    const goal = story.goal?.trim();
+    const benefit = story.benefit?.trim();
+    const ac = story.acceptanceCriteria?.trim();
+    const gherkin = gherkinContent?.trim();
+    const hasFullUserStoryLine = Boolean(role && goal && benefit);
+    const sections = [];
+    if (hasFullUserStoryLine) {
+        sections.push(`As a **${role}**, I want **${goal}** so that **${benefit}**.`);
+    }
+    if (ac)
+        sections.push(`**Acceptance criteria**\n\n${ac}`);
+    if (gherkin)
+        sections.push(`**Gherkin scenarios**\n\n\`\`\`gherkin\n${gherkin}\n\`\`\``);
+    return sections.join('\n\n');
+}
+/** Render parsed task lines to markdown checkboxes (Linear description). */
+export function formatTaskCheckboxBody(parsed) {
+    if (parsed.length === 0)
+        return '';
+    return parsed
+        .map((p) => {
+        const mark = p.done ? 'x' : ' ';
+        if (p.depth === 0) {
+            return `- [${mark}] **${p.id}** ${p.title}`;
+        }
+        return `  - [${mark}] ${p.id} ${p.title}`;
+    })
+        .join('\n');
+}
+/**
+ * Build a merged task-list body for a feature — concatenates every task
+ * artifact whose `featureId` matches, parses its checkboxes, renders them,
+ * and (when multiple files exist) prefixes each section with its task id
+ * as an `## h2`. Returns `''` when there's nothing to sync.
+ */
+export async function buildMergedTaskListBody(projectDir, config, featureId, taskFiles) {
+    const sections = [];
+    const sorted = [...taskFiles].sort((a, b) => a.id.localeCompare(b.id, undefined, { numeric: true }));
+    for (const tf of sorted) {
+        const raw = await readArtifactRaw(projectDir, config, 'task', tf.id);
+        if (!raw)
+            continue;
+        const data = (await readArtifact(projectDir, config, 'task', tf.id))?.data;
+        const fId = toOptionalString(data?.featureId);
+        if (fId !== featureId)
+            continue;
+        const parsed = parseTaskMarkdown(raw);
+        if (parsed.length === 0)
+            continue;
+        const body = formatTaskCheckboxBody(parsed);
+        if (taskFiles.length > 1) {
+            sections.push(`## ${tf.id}\n\n${body}`);
+        }
+        else {
+            sections.push(body);
+        }
+    }
+    return sections.join('\n\n');
+}
+/**
+ * Extract the markdown body of a standalone artifact (QT / BL) for pushing
+ * to Linear as an issue description.
+ *
+ * Strips:
+ *   - the frontmatter block (YAML between the `---` markers)
+ *   - the top-level `# <ID>: <title>` heading (Linear shows the title
+ *     separately, so repeating it in the description is noise)
+ *
+ * Everything else — prose, sub-headings, checkbox lists — is preserved
+ * verbatim. Linear renders standard markdown, so checkboxes stay checkboxes,
+ * `## sections` stay sections, links stay clickable.
+ */
+export function buildStandaloneArtifactBody(raw, id) {
+    // Strip frontmatter if present.
+    let body = raw;
+    const fmMatch = /^---[^\S\r\n]*\r?\n[\s\S]*?\r?\n---[^\S\r\n]*\r?\n?/.exec(raw);
+    if (fmMatch) {
+        body = raw.slice(fmMatch[0].length);
+    }
+    // Drop leading blank lines — markdown files typically have a blank line
+    // between the frontmatter's closing `---` and the first `#` heading.
+    body = body.replace(/^\s*\r?\n/, '').trimStart();
+    // Strip a single top-level `# <ID>:...` or `# <anything>` heading at the
+    // start of the body, plus the blank line that typically follows it.
+    const escapedId = id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const titleHeadingRegex = new RegExp(`^#\\s+(?:${escapedId}:\\s*)?.*\\r?\\n(?:\\r?\\n)?`);
+    body = body.replace(titleHeadingRegex, '');
+    return body.trimEnd();
+}
+/**
+ * Backlog item → Linear issue body. Priority + tags + description + optional
+ * acceptance criteria + notes. Accepts the generic frontmatter record shape
+ * because backlog items aren't currently loaded via a typed interface.
+ */
+export function buildBacklogItemBody(bl) {
+    const fm = bl.frontmatter;
+    const lines = [];
+    const priority = toOptionalString(fm.priority);
+    if (priority)
+        lines.push(`**Priority:** ${priority}`);
+    if (Array.isArray(fm.tags) && fm.tags.length > 0) {
+        const tags = fm.tags.filter((t) => typeof t === 'string');
+        if (tags.length)
+            lines.push(`**Tags:** ${tags.join(', ')}`);
+    }
+    const description = toOptionalString(fm.description);
+    if (description)
+        lines.push(description.trim());
+    const ac = toOptionalString(fm.acceptanceCriteria);
+    if (ac)
+        lines.push(`**Acceptance criteria**\n\n${ac.trim()}`);
+    const notes = toOptionalString(fm.notes);
+    if (notes)
+        lines.push(`**Notes**\n\n${notes.trim()}`);
+    return lines.join('\n\n');
+}
+//# sourceMappingURL=body-formatters.js.map

package/dist/services/linear/body-formatters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"body-formatters.js","sourceRoot":"","sources":["../../../src/services/linear/body-formatters.ts"],"names":[],"mappings":"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"}

package/dist/services/linear/constants.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Linear integration constants + id-shape validators + input-safety helpers.
+ *
+ * All field-limit values here are enforced at the SDK-wrapper layer in
+ * `src/services/linear-service.ts` so that every caller gets the guard for
+ * free. Shape validators (`isLikelyLinear*Id`) fence off stale frontmatter
+ * before it reaches the Linear API.
+ */
+/** Credential-service provider key under which the Linear PAT is stored. */
+export declare const LINEAR_CREDENTIAL_KEY: "linear";
+/**
+ * Linear's backend enforces per-field length limits on every create/update
+ * mutation. Defend at the SDK-wrapper layer so callers don't have to think
+ * about them. Names / titles: confirmed or best-known caps; descriptions:
+ * conservative floors well under Linear's real ceilings (markdown + HTML
+ * are both accepted; real limits are in the tens of thousands).
+ */
+export declare const LINEAR_FIELD_LIMITS: {
+    /** ProjectMilestone.name — confirmed 80 by `Argument Validation Error`. */
+    readonly milestoneName: 80;
+    /** IssueLabel.name — Linear team labels cap ~64 chars. */
+    readonly labelName: 64;
+    /** Project.name — generous cap. */
+    readonly projectName: 256;
+    /** Issue.title — Linear issue title cap ~255. */
+    readonly issueTitle: 255;
+    /** Project.description — conservative floor; real Linear ceiling is higher. */
+    readonly projectDescription: 50000;
+    /** ProjectMilestone.description. */
+    readonly milestoneDescription: 50000;
+    /** IssueLabel.description — labels rarely need long descriptions. */
+    readonly labelDescription: 500;
+    /** Issue.description (markdown body). */
+    readonly issueDescription: 65000;
+};
+/**
+ * Truncate a string to Linear's character limit for a given field. Logs a
+ * warning on truncation so the operator can spot it in the push output.
+ */
+export declare function truncateForLinear(value: string, maxLen: number, fieldLabel: string): string;
+/**
+ * Non-empty guard for required Linear name/title fields. Fails fast with an
+ * actionable message before the API would reject the call.
+ */
+export declare function requireNonEmpty(value: string | null | undefined, fieldLabel: string): string;
+/**
+ * Heuristic: Linear workflow state id (uuid) vs human-readable state name.
+ * The `/i` flag is intentional — Linear's API canonicalizes UUIDs to
+ * lowercase, but defensive acceptance of uppercase hex matches RFC 4122
+ * and protects against tools that normalize differently.
+ */
+export declare function isLikelyLinearWorkflowStateId(s: string): boolean;
+/**
+ * Validate that a value plausibly identifies a Linear issue. Two valid shapes:
+ *   1. UUIDv4 (e.g. `9b2f4c3e-...`) — canonical API form
+ *   2. Linear identifier (e.g. `ENG-42`) — human-readable, also accepted by `client.issue()`
+ * Anything else is treated as stale/corrupted frontmatter and skipped before
+ * hitting the API.
+ */
+export declare function isLikelyLinearIssueId(s: string): boolean;
+//# sourceMappingURL=constants.d.ts.map

package/dist/services/linear/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/services/linear/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,4EAA4E;AAC5E,eAAO,MAAM,qBAAqB,EAAG,QAAiB,CAAC;AAEvD;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB;IAC9B,2EAA2E;;IAE3E,0DAA0D;;IAE1D,mCAAmC;;IAEnC,iDAAiD;;IAEjD,+EAA+E;;IAE/E,oCAAoC;;IAEpC,qEAAqE;;IAErE,yCAAyC;;CAEjC,CAAC;AAEX;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAQ3F;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAQ5F;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAIhE;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAKxD"}

package/dist/services/linear/constants.js

@@ -0,0 +1,84 @@
+/**
+ * Linear integration constants + id-shape validators + input-safety helpers.
+ *
+ * All field-limit values here are enforced at the SDK-wrapper layer in
+ * `src/services/linear-service.ts` so that every caller gets the guard for
+ * free. Shape validators (`isLikelyLinear*Id`) fence off stale frontmatter
+ * before it reaches the Linear API.
+ */
+import { logger } from '../../utils/logger.js';
+/** Credential-service provider key under which the Linear PAT is stored. */
+export const LINEAR_CREDENTIAL_KEY = 'linear';
+/**
+ * Linear's backend enforces per-field length limits on every create/update
+ * mutation. Defend at the SDK-wrapper layer so callers don't have to think
+ * about them. Names / titles: confirmed or best-known caps; descriptions:
+ * conservative floors well under Linear's real ceilings (markdown + HTML
+ * are both accepted; real limits are in the tens of thousands).
+ */
+export const LINEAR_FIELD_LIMITS = {
+    /** ProjectMilestone.name — confirmed 80 by `Argument Validation Error`. */
+    milestoneName: 80,
+    /** IssueLabel.name — Linear team labels cap ~64 chars. */
+    labelName: 64,
+    /** Project.name — generous cap. */
+    projectName: 256,
+    /** Issue.title — Linear issue title cap ~255. */
+    issueTitle: 255,
+    /** Project.description — conservative floor; real Linear ceiling is higher. */
+    projectDescription: 50_000,
+    /** ProjectMilestone.description. */
+    milestoneDescription: 50_000,
+    /** IssueLabel.description — labels rarely need long descriptions. */
+    labelDescription: 500,
+    /** Issue.description (markdown body). */
+    issueDescription: 65_000,
+};
+/**
+ * Truncate a string to Linear's character limit for a given field. Logs a
+ * warning on truncation so the operator can spot it in the push output.
+ */
+export function truncateForLinear(value, maxLen, fieldLabel) {
+    const trimmed = value.trim();
+    if (trimmed.length <= maxLen)
+        return trimmed;
+    const truncated = trimmed.slice(0, maxLen);
+    logger.warn(`${fieldLabel} truncated from ${trimmed.length} → ${maxLen} chars to satisfy Linear's limit.`);
+    return truncated;
+}
+/**
+ * Non-empty guard for required Linear name/title fields. Fails fast with an
+ * actionable message before the API would reject the call.
+ */
+export function requireNonEmpty(value, fieldLabel) {
+    const trimmed = typeof value === 'string' ? value.trim() : '';
+    if (!trimmed) {
+        throw new Error(`${fieldLabel} is empty — Linear requires a non-empty value. Add a title to the OpenPlanr artifact and re-run.`);
+    }
+    return trimmed;
+}
+/**
+ * Heuristic: Linear workflow state id (uuid) vs human-readable state name.
+ * The `/i` flag is intentional — Linear's API canonicalizes UUIDs to
+ * lowercase, but defensive acceptance of uppercase hex matches RFC 4122
+ * and protects against tools that normalize differently.
+ */
+export function isLikelyLinearWorkflowStateId(s) {
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(s.trim());
+}
+/**
+ * Validate that a value plausibly identifies a Linear issue. Two valid shapes:
+ *   1. UUIDv4 (e.g. `9b2f4c3e-...`) — canonical API form
+ *   2. Linear identifier (e.g. `ENG-42`) — human-readable, also accepted by `client.issue()`
+ * Anything else is treated as stale/corrupted frontmatter and skipped before
+ * hitting the API.
+ */
+export function isLikelyLinearIssueId(s) {
+    const trimmed = s.trim();
+    if (trimmed.length === 0)
+        return false;
+    if (isLikelyLinearWorkflowStateId(trimmed))
+        return true;
+    return /^[A-Z]{2,}-\d+$/.test(trimmed);
+}
+//# sourceMappingURL=constants.js.map

package/dist/services/linear/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../src/services/linear/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAE/C,4EAA4E;AAC5E,MAAM,CAAC,MAAM,qBAAqB,GAAG,QAAiB,CAAC;AAEvD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,2EAA2E;IAC3E,aAAa,EAAE,EAAE;IACjB,0DAA0D;IAC1D,SAAS,EAAE,EAAE;IACb,mCAAmC;IACnC,WAAW,EAAE,GAAG;IAChB,iDAAiD;IACjD,UAAU,EAAE,GAAG;IACf,+EAA+E;IAC/E,kBAAkB,EAAE,MAAM;IAC1B,oCAAoC;IACpC,oBAAoB,EAAE,MAAM;IAC5B,qEAAqE;IACrE,gBAAgB,EAAE,GAAG;IACrB,yCAAyC;IACzC,gBAAgB,EAAE,MAAM;CAChB,CAAC;AAEX;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAa,EAAE,MAAc,EAAE,UAAkB;IACjF,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,OAAO,CAAC,MAAM,IAAI,MAAM;QAAE,OAAO,OAAO,CAAC;IAC7C,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IAC3C,MAAM,CAAC,IAAI,CACT,GAAG,UAAU,mBAAmB,OAAO,CAAC,MAAM,MAAM,MAAM,mCAAmC,CAC9F,CAAC;IACF,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,KAAgC,EAAE,UAAkB;IAClF,MAAM,OAAO,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9D,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,GAAG,UAAU,kGAAkG,CAChH,CAAC;IACJ,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,6BAA6B,CAAC,CAAS;IACrD,OAAO,4EAA4E,CAAC,IAAI,CACtF,CAAC,CAAC,IAAI,EAAE,CACT,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,CAAS;IAC7C,MAAM,OAAO,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACzB,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACvC,IAAI,6BAA6B,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IACxD,OAAO,iBAAiB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AACzC,CAAC"}

package/dist/services/linear/errors.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Linear error classification, user-facing mapping, and retry wrapper.
+ *
+ * Two responsibilities:
+ *   1. Map raw SDK errors to user-friendly messages (branded guidance for
+ *      auth / network / rate-limit; surfaced friendly SDK message for other
+ *      classified types; sanitized fallback for unclassified errors).
+ *   2. Wrap Linear calls with small exponential backoff that honours
+ *      `RatelimitedLinearError.retryAfter`.
+ */
+/** Wraps a Linear call with small exponential backoff on rate limit / network errors. */
+export declare function withLinearRetry<T>(op: string, fn: () => Promise<T>, retries?: number): Promise<T>;
+export declare function mapLinearError(err: unknown, context: string): Error;
+//# sourceMappingURL=errors.d.ts.map

package/dist/services/linear/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/services/linear/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAgCH,yFAAyF;AACzF,wBAAsB,eAAe,CAAC,CAAC,EACrC,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,GAAE,MAAwB,GAChC,OAAO,CAAC,CAAC,CAAC,CA4BZ;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,KAAK,CA6CnE"}

package/dist/services/linear/errors.js

@@ -0,0 +1,106 @@
+/**
+ * Linear error classification, user-facing mapping, and retry wrapper.
+ *
+ * Two responsibilities:
+ *   1. Map raw SDK errors to user-friendly messages (branded guidance for
+ *      auth / network / rate-limit; surfaced friendly SDK message for other
+ *      classified types; sanitized fallback for unclassified errors).
+ *   2. Wrap Linear calls with small exponential backoff that honours
+ *      `RatelimitedLinearError.retryAfter`.
+ */
+import { LinearError, LinearErrorType, RatelimitedLinearError } from '@linear/sdk';
+import { logger } from '../../utils/logger.js';
+const DEFAULT_RETRIES = 3;
+/**
+ * Extract the first user-facing message from a LinearError. The SDK exposes
+ * per-GraphQL-error `.message` strings on `errors[]` — these are backend-
+ * authored user descriptions (e.g., "Milestone already exists with this
+ * name"). Falls back to `err.message` and finally to the error `type`.
+ * Safe to surface — this is not the raw query/variables.
+ */
+function extractLinearFriendlyMessage(err) {
+    const first = err.errors?.[0]?.message?.trim();
+    if (first)
+        return first;
+    const top = err.message?.trim();
+    if (top)
+        return top;
+    const type = err.type;
+    return type || undefined;
+}
+function isRetriableLinearError(err) {
+    if (err instanceof LinearError) {
+        const t = err.type ?? LinearErrorType.Unknown;
+        return t === LinearErrorType.Ratelimited || t === LinearErrorType.NetworkError;
+    }
+    if (err instanceof Error && err.name === 'AbortError')
+        return true;
+    return false;
+}
+/** Wraps a Linear call with small exponential backoff on rate limit / network errors. */
+export async function withLinearRetry(op, fn, retries = DEFAULT_RETRIES) {
+    let last;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            last = err;
+            if (attempt < retries && isRetriableLinearError(err)) {
+                // Prefer Linear's own `Retry-After` when the error is a rate-limit
+                // (surfaced on the `RatelimitedLinearError` subclass as a seconds
+                // value). Fall back to exponential backoff for network errors and
+                // when the server didn't advertise a retry hint. Use `Math.max` so
+                // we respect both: never retry sooner than Linear asked, never
+                // faster than our own backoff schedule.
+                const retryAfterMs = err instanceof RatelimitedLinearError && typeof err.retryAfter === 'number'
+                    ? Math.max(0, err.retryAfter) * 1000
+                    : 0;
+                const backoffMs = Math.min(30_000, 500 * 2 ** attempt);
+                const waitMs = Math.max(retryAfterMs, backoffMs);
+                logger.dim(`Linear ${op}: retrying in ${waitMs}ms (attempt ${attempt + 1}/${retries})...`);
+                await new Promise((r) => setTimeout(r, waitMs));
+                continue;
+            }
+            throw mapLinearError(err, op);
+        }
+    }
+    throw mapLinearError(last, op);
+}
+export function mapLinearError(err, context) {
+    if (err instanceof Error && err.name === 'AbortError') {
+        return new Error(`Network error while ${context}: request was cancelled or timed out.`);
+    }
+    if (err instanceof LinearError) {
+        const t = err.type ?? LinearErrorType.Unknown;
+        if (t === LinearErrorType.AuthenticationError) {
+            return new Error(`Linear rejected this token while ${context}. Create a new PAT at https://linear.app/settings/account/security (app, read, write as needed) and run \`planr linear init\` again.`);
+        }
+        if (t === LinearErrorType.NetworkError) {
+            return new Error(`Cannot reach Linear while ${context}. Check your network connection, try again, and see https://status.linear.app for outages.`);
+        }
+        if (t === LinearErrorType.Ratelimited) {
+            return new Error('Linear rate limit reached. Wait about 1–2 minutes (longer if you are polling heavily), then retry. See https://status.linear.app if issues persist.');
+        }
+        // For other classified LinearError types (Forbidden, InvalidInput, UserError,
+        // FeatureNotAccessible, Internal, LockTimeout, UsageLimitExceeded, Graphql,
+        // Other, Bootstrap, Unknown) surface the SDK's friendly .message string —
+        // backend-authored user descriptions like "Milestone name already exists
+        // in project" or "Input invalid: projectId". Also log the full object at
+        // debug level for --verbose diagnostics.
+        logger.debug(`Linear error (${context}, type=${t})`, err);
+        const friendly = extractLinearFriendlyMessage(err);
+        const suffix = friendly ? `: ${friendly}` : '';
+        if (t === LinearErrorType.Forbidden) {
+            return new Error(`Permission denied while ${context}${suffix}. Your token may be missing the required scope, or your user cannot access this resource.`);
+        }
+        return new Error(`Linear error while ${context} (${t})${suffix}`);
+    }
+    // Unknown / unclassified error class: log the full object at debug level so
+    // operators can inspect it with `--verbose`, but do NOT surface the raw
+    // message to end users — could contain arbitrary response bodies.
+    logger.debug(`Linear error (${context})`, err);
+    const klass = err instanceof Error ? err.constructor.name : 'Unknown';
+    return new Error(`Linear error while ${context} (${klass}). Re-run with --verbose for diagnostic details.`);
+}
+//# sourceMappingURL=errors.js.map

package/dist/services/linear/errors.js.map

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

package/dist/services/linear/estimate-resolver.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Scale-aware snapping from OpenPlanr `storyPoints` → Linear `estimate` field.
+ *
+ * Linear's estimate field is numeric and must match the team's configured
+ * scale (`fibonacci`, `linear`, `exponential`, or `tShirt`). A value that
+ * isn't on the scale is rejected by the API, so we snap to the nearest
+ * allowed value before sending. Callers use the returned snap event to emit
+ * a debug log once per transformation.
+ *
+ * Scales mirror Linear's own SDK values — see `LinearIssueEstimationType`
+ * in `src/models/types.ts`.
+ */
+import type { LinearIssueEstimationType } from '../../models/types.js';
+/**
+ * Result of resolving a local estimate for a push. Exactly one of
+ * `estimate` (mapped value, ready to send to Linear) or `reason` (why the
+ * field is being omitted) is populated.
+ */
+export type EstimateResolution = {
+    kind: 'mapped';
+    estimate: number;
+    originalValue: number;
+    snapped: boolean;
+} | {
+    kind: 'skip-not-used';
+} | {
+    kind: 'skip-t-shirt';
+} | {
+    kind: 'skip-no-local-value';
+} | {
+    kind: 'skip-invalid-value';
+    rawValue: unknown;
+};
+/**
+ * Resolve a local `storyPoints` (or `estimatedPoints`) value to a Linear
+ * `estimate` value given the team's scale.
+ *
+ * Precedence for the raw local value:
+ *   1. `frontmatter.estimatedPoints` — canonical name written by
+ *      `planr estimate --save` (see `src/cli/commands/estimate.ts`).
+ *   2. `frontmatter.storyPoints` — alias accepted for hand-edited files or
+ *      direct AI-response copies that used the schema field name verbatim.
+ *
+ * Returns one of:
+ *   - `mapped` — include `estimate: <value>` in the push input
+ *   - `skip-*` — omit the `estimate` field; `kind` carries the reason for
+ *      logging / dry-run display
+ */
+export declare function resolveEstimateForPush(frontmatter: Record<string, unknown>, scale: LinearIssueEstimationType | string | undefined): EstimateResolution;
+//# sourceMappingURL=estimate-resolver.d.ts.map

package/dist/services/linear/estimate-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"estimate-resolver.d.ts","sourceRoot":"","sources":["../../../src/services/linear/estimate-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAqBvE;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAC7E;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,GACzB;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,GACxB;IAAE,IAAI,EAAE,qBAAqB,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,oBAAoB,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,KAAK,EAAE,yBAAyB,GAAG,MAAM,GAAG,SAAS,GACpD,kBAAkB,CAyCpB"}

package/dist/services/linear/estimate-resolver.js

@@ -0,0 +1,82 @@
+/**
+ * Scale-aware snapping from OpenPlanr `storyPoints` → Linear `estimate` field.
+ *
+ * Linear's estimate field is numeric and must match the team's configured
+ * scale (`fibonacci`, `linear`, `exponential`, or `tShirt`). A value that
+ * isn't on the scale is rejected by the API, so we snap to the nearest
+ * allowed value before sending. Callers use the returned snap event to emit
+ * a debug log once per transformation.
+ *
+ * Scales mirror Linear's own SDK values — see `LinearIssueEstimationType`
+ * in `src/models/types.ts`.
+ */
+const FIBONACCI_SCALE = [0, 1, 2, 3, 5, 8, 13, 21];
+const LINEAR_SCALE = [0, 1, 2, 3, 4, 5];
+const EXPONENTIAL_SCALE = [0, 1, 2, 4, 8, 16];
+function snapToNearest(value, scale) {
+    let best = scale[0];
+    let bestDistance = Math.abs(value - best);
+    for (const candidate of scale) {
+        const distance = Math.abs(value - candidate);
+        // Break ties toward the larger value — under-estimating is a common
+        // planning bias; snapping up ("4 is really a 5") leans against it.
+        if (distance < bestDistance || (distance === bestDistance && candidate > best)) {
+            best = candidate;
+            bestDistance = distance;
+        }
+    }
+    return best;
+}
+/**
+ * Resolve a local `storyPoints` (or `estimatedPoints`) value to a Linear
+ * `estimate` value given the team's scale.
+ *
+ * Precedence for the raw local value:
+ *   1. `frontmatter.estimatedPoints` — canonical name written by
+ *      `planr estimate --save` (see `src/cli/commands/estimate.ts`).
+ *   2. `frontmatter.storyPoints` — alias accepted for hand-edited files or
+ *      direct AI-response copies that used the schema field name verbatim.
+ *
+ * Returns one of:
+ *   - `mapped` — include `estimate: <value>` in the push input
+ *   - `skip-*` — omit the `estimate` field; `kind` carries the reason for
+ *      logging / dry-run display
+ */
+export function resolveEstimateForPush(frontmatter, scale) {
+    if (scale === 'notUsed' || !scale) {
+        return { kind: 'skip-not-used' };
+    }
+    if (scale === 'tShirt') {
+        // No safe numeric → XS/S/M/L/XL mapping without user config. Skip.
+        return { kind: 'skip-t-shirt' };
+    }
+    const rawLocal = frontmatter.estimatedPoints !== undefined
+        ? frontmatter.estimatedPoints
+        : frontmatter.storyPoints;
+    if (rawLocal === undefined || rawLocal === null || rawLocal === '') {
+        return { kind: 'skip-no-local-value' };
+    }
+    const parsed = typeof rawLocal === 'number' ? rawLocal : Number(rawLocal);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        return { kind: 'skip-invalid-value', rawValue: rawLocal };
+    }
+    const allowed = scale === 'fibonacci'
+        ? FIBONACCI_SCALE
+        : scale === 'linear'
+            ? LINEAR_SCALE
+            : scale === 'exponential'
+                ? EXPONENTIAL_SCALE
+                : undefined;
+    if (!allowed) {
+        // Unknown scale value returned by Linear — skip rather than guess.
+        return { kind: 'skip-not-used' };
+    }
+    const snapped = snapToNearest(parsed, allowed);
+    return {
+        kind: 'mapped',
+        estimate: snapped,
+        originalValue: parsed,
+        snapped: snapped !== parsed,
+    };
+}
+//# sourceMappingURL=estimate-resolver.js.map

package/dist/services/linear/estimate-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"estimate-resolver.js","sourceRoot":"","sources":["../../../src/services/linear/estimate-resolver.ts"],"names":[],"mappings":"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"}