openplanr 1.2.7 → 1.3.0

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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"}

package/dist/services/linear/plan-builders.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Pure plan-building for `planr linear push --dry-run`. Takes loaded scopes
+ * and returns `LinearPushPlan` objects with per-kind row counts. No Linear
+ * API calls; no mutations. Epic-scope plans cascade rows for linked QT/BL.
+ */
+import type { Epic, Feature, OpenPlanrConfig, UserStory } from '../../models/types.js';
+import { type ScopedFeature, type ScopedTaskFile } from './scope-loaders.js';
+export type LinearPushItemKind = 'project' | 'feature' | 'story' | 'taskList' | 'quickTask' | 'backlogItem';
+export type LinearPushAction = 'create' | 'update' | 'skip';
+/** Scope of a granular push — what subtree `runLinearPush(artifactId)` touches. */
+export type LinearPushScope = 'epic' | 'feature' | 'story' | 'taskFile' | 'quick' | 'backlog';
+export interface LinearPushPlanRow {
+    kind: LinearPushItemKind;
+    /** Epic id, feature id, story id, or task-file id for this row. */
+    artifactId: string;
+    title: string;
+    action: LinearPushAction;
+    detail?: string;
+}
+export interface LinearPushPlan {
+    /** The artifact the user pointed `planr linear push` at (any supported prefix). */
+    rootArtifactId: string;
+    /** The epic that owns this push's subtree; `undefined` for standalone QT/BL pushes. */
+    epicId?: string;
+    scope: LinearPushScope;
+    rows: LinearPushPlanRow[];
+    /** Counts by kind for non-`skip` rows. Missing kinds are 0. */
+    counts: {
+        project: number;
+        features: number;
+        stories: number;
+        taskLists: number;
+        quickTasks: number;
+        backlogItems: number;
+        total: number;
+    };
+}
+/**
+ * Extract the linked epic id from QT / BL frontmatter. Canonical field is
+ * `epicId`; `parentEpic` is accepted as a compat alias for hand-authored
+ * files. Empty strings are normalised to `undefined`.
+ */
+export declare function getLinkedEpicId(fm: Record<string, unknown>): string | undefined;
+export declare function projectRow(epic: Epic): LinearPushPlanRow;
+export declare function featureRow(f: Feature): LinearPushPlanRow;
+export declare function storyRow(s: UserStory): LinearPushPlanRow;
+export declare function taskListPlanRow(featureId: string, taskFiles: ScopedTaskFile[], hasBody: boolean, hadIssue: boolean): LinearPushPlanRow;
+export declare function applyUpdateOnly(rows: LinearPushPlanRow[], updateOnly: boolean): LinearPushPlanRow[];
+export declare function summarizePlan(rootArtifactId: string, epicId: string | undefined, scope: LinearPushScope, rows: LinearPushPlanRow[]): LinearPushPlan;
+export declare function buildFeaturePlanRows(projectDir: string, config: OpenPlanrConfig, sf: ScopedFeature): Promise<LinearPushPlanRow[]>;
+export declare function buildEpicPlanRows(projectDir: string, config: OpenPlanrConfig, epicScope: {
+    epic: Epic;
+    features: ScopedFeature[];
+}): Promise<LinearPushPlanRow[]>;
+/**
+ * Build a push preview (and counts) for `planr linear push --dry-run` at any
+ * granularity. Accepts any supported artifact id prefix (EPIC/FEAT/US/TASK/
+ * QT/BL); returns `null` when the artifact can't be resolved or is not
+ * pushable (ADR/SPRINT/checklist).
+ */
+export declare function buildLinearPushPlan(projectDir: string, config: OpenPlanrConfig, artifactId: string, options?: {
+    updateOnly?: boolean;
+}): Promise<LinearPushPlan | null>;
+//# sourceMappingURL=plan-builders.d.ts.map

package/dist/services/linear/plan-builders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-builders.d.ts","sourceRoot":"","sources":["../../../src/services/linear/plan-builders.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAGvF,OAAO,EAOL,KAAK,aAAa,EAClB,KAAK,cAAc,EACpB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,MAAM,kBAAkB,GAC1B,SAAS,GACT,SAAS,GACT,OAAO,GACP,UAAU,GACV,WAAW,GACX,aAAa,CAAC;AAElB,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE5D,mFAAmF;AACnF,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,UAAU,GAAG,OAAO,GAAG,SAAS,CAAC;AAE9F,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,kBAAkB,CAAC;IACzB,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,gBAAgB,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,mFAAmF;IACnF,cAAc,EAAE,MAAM,CAAC;IACvB,uFAAuF;IACvF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,eAAe,CAAC;IACvB,IAAI,EAAE,iBAAiB,EAAE,CAAC;IAC1B,+DAA+D;IAC/D,MAAM,EAAE;QACN,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;QACrB,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;CACH;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,SAAS,CAE/E;AAUD,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,iBAAiB,CAQxD;AAED,wBAAgB,UAAU,CAAC,CAAC,EAAE,OAAO,GAAG,iBAAiB,CAOxD;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,SAAS,GAAG,iBAAiB,CAOxD;AAED,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,cAAc,EAAE,EAC3B,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,OAAO,GAChB,iBAAiB,CAiBnB;AAED,wBAAgB,eAAe,CAC7B,IAAI,EAAE,iBAAiB,EAAE,EACzB,UAAU,EAAE,OAAO,GAClB,iBAAiB,EAAE,CAarB;AAED,wBAAgB,aAAa,CAC3B,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,KAAK,EAAE,eAAe,EACtB,IAAI,EAAE,iBAAiB,EAAE,GACxB,cAAc,CAwBhB;AAMD,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,eAAe,EACvB,EAAE,EAAE,aAAa,GAChB,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAiB9B;AAED,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,eAAe,EACvB,SAAS,EAAE;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,aAAa,EAAE,CAAA;CAAE,GACnD,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAiC9B;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,eAAe,EACvB,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE;IAAE,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,GACjC,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CA2FhC"}