@enrichlayer/el-linear 1.4.0 → 1.6.0

package/dist/utils/legacy-config-detection.js

@@ -0,0 +1,90 @@
+/**
+ * Detects "legacy drift" — the on-disk state where a user upgraded el-linear
+ * to >=1.4.0 (named profiles) while their old `~/.config/el-linear/config.json`
+ * is still present but the legacy single-file `token` (and any per-profile
+ * token) is missing or unreadable. In that state every command fails with
+ * "No API token found" and the user has no clear migration path.
+ *
+ * This module is **pure detection** — it returns a discriminated state and
+ * nothing else. The hint emission lives in `migration-hint.ts` and is wired
+ * into the auth-failure path (`auth.ts`) so the user gets a single clear
+ * stderr line *before* the regular auth error fires.
+ *
+ * The state shape is intentionally a discriminated union so callers can match
+ * exhaustively without re-checking individual booleans:
+ *
+ *   { kind: 'no-drift' }
+ *     — healthy: legacy single-file layout *or* a working active profile.
+ *
+ *   { kind: 'legacy-no-token' }
+ *     — `config.json` exists but no token (legacy or per-profile) does. This
+ *       is the post-upgrade case: 1.4.0 expects per-profile tokens; legacy
+ *       config was never migrated.
+ *
+ *   { kind: 'broken-active-profile' }
+ *     — `active-profile` points at a name whose directory doesn't exist.
+ *       Typically caused by an interrupted `profile remove` or a hand-edit.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { ACTIVE_PROFILE_FILE, CONFIG_PATH, PROFILES_DIR, TOKEN_PATH, } from "../config/paths.js";
+const DEFAULT_FS_OPS = {
+    existsSync: (p) => fs.existsSync(p),
+    readFileSync: (p) => fs.readFileSync(p, "utf8"),
+    readdirSync: (p) => fs.readdirSync(p),
+};
+/**
+ * Detect drift between the legacy single-file layout and the >=1.4 named-
+ * profiles layout. Pure — `fsImpl` is overridable so tests can drive every
+ * branch without touching the filesystem.
+ */
+export function detectLegacyDrift(fsImpl = DEFAULT_FS_OPS) {
+    // Branch 1: broken active-profile pointer.
+    // The `active-profile` marker names a profile that doesn't exist on disk —
+    // classic post-`profile remove` orphan, or a hand-edit typo. We classify
+    // this *before* the legacy-no-token branch because the user explicitly
+    // asked for that profile; the right fix is `profile use <good-name>`, not
+    // migration.
+    if (fsImpl.existsSync(ACTIVE_PROFILE_FILE)) {
+        let pointedAt = "";
+        try {
+            pointedAt = fsImpl.readFileSync(ACTIVE_PROFILE_FILE).trim();
+        }
+        catch {
+            pointedAt = "";
+        }
+        if (pointedAt.length > 0) {
+            const profileDir = path.join(PROFILES_DIR, pointedAt);
+            if (!fsImpl.existsSync(profileDir)) {
+                return { kind: "broken-active-profile", pointedAt };
+            }
+        }
+    }
+    // Branch 2: legacy drift.
+    // Legacy `config.json` exists; legacy `token` doesn't; no profiles configured.
+    // "No profiles configured" = profiles dir missing OR exists-but-empty.
+    if (!fsImpl.existsSync(CONFIG_PATH)) {
+        return { kind: "no-drift" };
+    }
+    if (fsImpl.existsSync(TOKEN_PATH)) {
+        return { kind: "no-drift" };
+    }
+    const profilesEmpty = isProfilesDirEmpty(fsImpl);
+    if (!profilesEmpty) {
+        return { kind: "no-drift" };
+    }
+    return { kind: "legacy-no-token", legacyConfigPath: CONFIG_PATH };
+}
+function isProfilesDirEmpty(fsImpl) {
+    if (!fsImpl.existsSync(PROFILES_DIR))
+        return true;
+    try {
+        const entries = fsImpl.readdirSync(PROFILES_DIR);
+        return entries.length === 0;
+    }
+    catch {
+        // Unreadable dir — treat as empty for the purposes of drift detection
+        // so we don't suppress the hint on a permissions edge case.
+        return true;
+    }
+}

package/dist/utils/linear-service.d.ts

@@ -1,8 +1,23 @@
 import type { LinearComment, LinearCycleDetail, LinearCycleSummary, LinearLabel, LinearProject, LinearTeam, LinearUser } from "../types/linear.js";
-import { type AuthOptions } from "./auth.js";
+import type { AuthOptions } from "./auth.js";
+/**
+ * Constructor arg shapes for `LinearService`. Three variants:
+ *   - `string` → personal API token (legacy; sent without `Bearer` prefix).
+ *   - `{apiKey: string}` → personal API token (explicit).
+ *   - `{oauthToken: string}` → OAuth access token (sent as
+ *     `Authorization: Bearer <token>` via the SDK's accessToken option).
+ *
+ * The string variant exists because hundreds of call sites and tests pass
+ * a plain string. We continue to support it indefinitely.
+ */
+export type LinearServiceAuth = string | {
+    apiKey: string;
+} | {
+    oauthToken: string;
+};
 export declare class LinearService {
     private readonly client;
-    constructor(apiToken: string);
+    constructor(auth: LinearServiceAuth);
     resolveIssueId(issueId: string): Promise<string>;
     getTeams(limit?: number): Promise<LinearTeam[]>;
     resolveUserId(nameOrEmailOrId: string): Promise<string>;
@@ -23,4 +38,4 @@ export declare class LinearService {
     resolveCycleId(cycleNameOrId: string, teamFilter?: string): Promise<string>;
     resolveProjectId(projectNameOrId: string): Promise<string>;
 }
-export declare function createLinearService(options: AuthOptions): LinearService;
+export declare function createLinearService(options: AuthOptions): Promise<LinearService>;

package/dist/utils/linear-service.js

@@ -1,6 +1,6 @@
 import { LinearClient } from "@linear/sdk";
+import { getActiveAuth } from "../auth/token-resolver.js";
 import { resolveUserDisplayName } from "../config/resolver.js";
-import { getApiToken } from "./auth.js";
 import { toISOStringOrNow, toISOStringOrUndefined } from "./date-format.js";
 import { multipleMatchesError, notFoundError } from "./error-messages.js";
 import { parseIssueIdentifier } from "./identifier-parser.js";
@@ -21,10 +21,22 @@ function teamIdFilter(teamId) {
 function nonEmptyFilter(filter) {
     return Object.keys(filter).length > 0 ? filter : undefined;
 }
+function buildLinearClient(auth) {
+    if (typeof auth === "string") {
+        return new LinearClient({ apiKey: auth });
+    }
+    if ("oauthToken" in auth) {
+        // Linear's SDK natively supports OAuth via the `accessToken` option,
+        // which causes the underlying transport to send
+        // `Authorization: Bearer <token>` instead of the personal-token shape.
+        return new LinearClient({ accessToken: auth.oauthToken });
+    }
+    return new LinearClient({ apiKey: auth.apiKey });
+}
 export class LinearService {
     client;
-    constructor(apiToken) {
-        this.client = new LinearClient({ apiKey: apiToken });
+    constructor(auth) {
+        this.client = buildLinearClient(auth);
     }
     async resolveIssueId(issueId) {
         if (isUuid(issueId)) {
@@ -436,7 +448,10 @@ export class LinearService {
         return projectsConnection.nodes[0].id;
     }
 }
-export function createLinearService(options) {
-    const apiToken = getApiToken(options);
-    return new LinearService(apiToken);
+export async function createLinearService(options) {
+    const auth = await getActiveAuth(options);
+    if (auth.kind === "oauth") {
+        return new LinearService({ oauthToken: auth.token });
+    }
+    return new LinearService({ apiKey: auth.token });
 }

package/dist/utils/markdown-prosemirror.js

@@ -106,8 +106,11 @@ function parseBulletList(state, line) {
         return false;
     }
     const items = [];
-    while (state.i < state.lines.length && BULLET_RE.test(state.lines[state.i])) {
+    while (state.i < state.lines.length) {
         const m = state.lines[state.i].match(BULLET_RE);
+        if (!m) {
+            break;
+        }
         items.push({
             type: "listItem",
             content: [{ type: "paragraph", content: parseInline(m[1]) }],
@@ -122,9 +125,11 @@ function parseOrderedList(state, line) {
         return false;
     }
     const items = [];
-    while (state.i < state.lines.length &&
-        ORDERED_RE.test(state.lines[state.i])) {
+    while (state.i < state.lines.length) {
         const m = state.lines[state.i].match(ORDERED_RE);
+        if (!m) {
+            break;
+        }
         items.push({
             type: "listItem",
             content: [{ type: "paragraph", content: parseInline(m[1]) }],
@@ -139,9 +144,11 @@ function parseBlockquote(state) {
         return false;
     }
     const quoteLines = [];
-    while (state.i < state.lines.length &&
-        BLOCKQUOTE_RE.test(state.lines[state.i])) {
+    while (state.i < state.lines.length) {
         const m = state.lines[state.i].match(BLOCKQUOTE_RE);
+        if (!m) {
+            break;
+        }
         quoteLines.push(m[1]);
         state.i++;
     }
@@ -283,7 +290,7 @@ function findEarliestInlineMatch(text) {
     const codeMatch = text.match(INLINE_CODE_RE);
     if (codeMatch) {
         candidates.push({
-            index: codeMatch.index,
+            index: codeMatch.index ?? 0,
             length: codeMatch[0].length,
             innerText: codeMatch[1],
             marks: [{ type: "code" }],
@@ -292,7 +299,7 @@ function findEarliestInlineMatch(text) {
     const linkMatch = text.match(INLINE_LINK_RE);
     if (linkMatch) {
         candidates.push({
-            index: linkMatch.index,
+            index: linkMatch.index ?? 0,
             length: linkMatch[0].length,
             innerText: linkMatch[1],
             marks: [{ type: "link", attrs: { href: linkMatch[2] } }],
@@ -301,7 +308,7 @@ function findEarliestInlineMatch(text) {
     const boldMatch = text.match(INLINE_BOLD_RE);
     if (boldMatch) {
         candidates.push({
-            index: boldMatch.index,
+            index: boldMatch.index ?? 0,
             length: boldMatch[0].length,
             innerText: boldMatch[1] ?? boldMatch[2],
             marks: [{ type: "bold" }],
@@ -310,7 +317,7 @@ function findEarliestInlineMatch(text) {
     const italicMatch = text.match(INLINE_ITALIC_RE);
     if (italicMatch) {
         candidates.push({
-            index: italicMatch.index,
+            index: italicMatch.index ?? 0,
             length: italicMatch[0].length,
             innerText: italicMatch[1] ?? italicMatch[2],
             marks: [{ type: "italic" }],

package/dist/utils/migration-hint.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Once-per-process stderr hint for legacy-config drift.
+ *
+ * Wired into the auth-failure path in `auth.ts`. When the legacy single-file
+ * config exists but no token can be found anywhere (the >=1.4 post-upgrade
+ * scenario), we emit one stderr line pointing the user at
+ * `el-linear profile migrate-legacy` *before* the regular "No API token
+ * found" error fires.
+ *
+ * Constraints:
+ *
+ * - **stderr only** — stdout is reserved for the JSON error payload that
+ *   machine callers parse, and the hint must not corrupt that stream.
+ * - **Once per process** — even if a script invokes el-linear in a tight
+ *   loop within a single Node process (uncommon but possible), only the
+ *   first failure prints. Anything more is noise.
+ * - **Suppressible** — `EL_LINEAR_SKIP_MIGRATION_HINT=1` silences the hint
+ *   for users who've decided to stay on the legacy layout intentionally.
+ *   The env var is read at *emission time*, not module load, so toggling
+ *   it in tests works without re-importing.
+ * - **Non-blocking** — never throws, never delays the underlying auth
+ *   error. The hint is purely informational.
+ */
+import { type DetectionFsOps, type LegacyDriftState } from "./legacy-config-detection.js";
+/**
+ * Test seam — resets the once-per-process latch so each test starts fresh.
+ * Production code never calls this.
+ */
+export declare function _resetMigrationHintForTests(): void;
+/**
+ * Emit the migration hint to stderr if (and only if) legacy drift is
+ * detected, the latch hasn't fired this process, and the suppress env var
+ * isn't set. Returns the detection state so callers can branch (or log).
+ *
+ * Optional `fsImpl` lets tests drive detection without touching disk.
+ * Optional `stderr` lets tests capture the output without spying on the
+ * global stream.
+ */
+export declare function maybeEmitMigrationHint(fsImpl?: DetectionFsOps, stderr?: {
+    write: (chunk: string) => void;
+}): LegacyDriftState;
+/**
+ * Render the hint string for a given state. Returns null when no hint
+ * should be emitted (no-drift). Exported for unit testing.
+ */
+export declare function formatHint(state: LegacyDriftState): string | null;

package/dist/utils/migration-hint.js

@@ -0,0 +1,90 @@
+/**
+ * Once-per-process stderr hint for legacy-config drift.
+ *
+ * Wired into the auth-failure path in `auth.ts`. When the legacy single-file
+ * config exists but no token can be found anywhere (the >=1.4 post-upgrade
+ * scenario), we emit one stderr line pointing the user at
+ * `el-linear profile migrate-legacy` *before* the regular "No API token
+ * found" error fires.
+ *
+ * Constraints:
+ *
+ * - **stderr only** — stdout is reserved for the JSON error payload that
+ *   machine callers parse, and the hint must not corrupt that stream.
+ * - **Once per process** — even if a script invokes el-linear in a tight
+ *   loop within a single Node process (uncommon but possible), only the
+ *   first failure prints. Anything more is noise.
+ * - **Suppressible** — `EL_LINEAR_SKIP_MIGRATION_HINT=1` silences the hint
+ *   for users who've decided to stay on the legacy layout intentionally.
+ *   The env var is read at *emission time*, not module load, so toggling
+ *   it in tests works without re-importing.
+ * - **Non-blocking** — never throws, never delays the underlying auth
+ *   error. The hint is purely informational.
+ */
+import { detectLegacyDrift, } from "./legacy-config-detection.js";
+let hintAlreadyEmitted = false;
+/**
+ * Test seam — resets the once-per-process latch so each test starts fresh.
+ * Production code never calls this.
+ */
+export function _resetMigrationHintForTests() {
+    hintAlreadyEmitted = false;
+}
+/**
+ * Emit the migration hint to stderr if (and only if) legacy drift is
+ * detected, the latch hasn't fired this process, and the suppress env var
+ * isn't set. Returns the detection state so callers can branch (or log).
+ *
+ * Optional `fsImpl` lets tests drive detection without touching disk.
+ * Optional `stderr` lets tests capture the output without spying on the
+ * global stream.
+ */
+export function maybeEmitMigrationHint(fsImpl, stderr = process.stderr) {
+    const state = detectLegacyDrift(fsImpl);
+    // Read the env var at call time — the suppress flag may be flipped between
+    // commands in long-lived test processes.
+    if (process.env.EL_LINEAR_SKIP_MIGRATION_HINT === "1") {
+        return state;
+    }
+    if (hintAlreadyEmitted) {
+        return state;
+    }
+    const message = formatHint(state);
+    if (message === null) {
+        return state;
+    }
+    hintAlreadyEmitted = true;
+    stderr.write(`${message}\n`);
+    return state;
+}
+/**
+ * Render the hint string for a given state. Returns null when no hint
+ * should be emitted (no-drift). Exported for unit testing.
+ */
+export function formatHint(state) {
+    if (state.kind === "no-drift")
+        return null;
+    if (state.kind === "broken-active-profile") {
+        return [
+            `el-linear: active profile "${state.pointedAt}" doesn't exist.`,
+            "Switch with:",
+            "",
+            "  el-linear profile use <name>",
+            "",
+            "Or list available profiles:",
+            "",
+            "  el-linear profile list",
+            "",
+            "Or suppress this hint with EL_LINEAR_SKIP_MIGRATION_HINT=1.",
+        ].join("\n");
+    }
+    // legacy-no-token
+    return [
+        `el-linear: legacy config detected at ${state.legacyConfigPath}`,
+        "but no token. Migrate with:",
+        "",
+        "  el-linear profile migrate-legacy [--name <profile>]",
+        "",
+        "Or suppress this hint with EL_LINEAR_SKIP_MIGRATION_HINT=1.",
+    ].join("\n");
+}

package/dist/utils/root-opts.d.ts

@@ -0,0 +1,11 @@
+import type { Command, OptionValues } from "commander";
+/**
+ * Extract root command options from inside a subcommand action handler.
+ *
+ * Commander guarantees `command.parent` exists inside any subcommand action,
+ * and `command.parent.parent` exists inside a nested subcommand action
+ * (e.g. `el-linear comments create` — the `create` command is nested under
+ * `comments`, which is nested under the root program). The non-null
+ * assertions live here so call sites can stay clean and typed.
+ */
+export declare function getRootOpts(command: Command): OptionValues;

package/dist/utils/root-opts.js

@@ -0,0 +1,13 @@
+/**
+ * Extract root command options from inside a subcommand action handler.
+ *
+ * Commander guarantees `command.parent` exists inside any subcommand action,
+ * and `command.parent.parent` exists inside a nested subcommand action
+ * (e.g. `el-linear comments create` — the `create` command is nested under
+ * `comments`, which is nested under the root program). The non-null
+ * assertions live here so call sites can stay clean and typed.
+ */
+export function getRootOpts(command) {
+    // biome-ignore lint/style/noNonNullAssertion: command.parent / .parent.parent are guaranteed by commander inside subcommand actions; see docstring
+    return (command.parent?.parent ?? command.parent).opts();
+}

package/dist/utils/validators.d.ts

@@ -1,4 +1,11 @@
 export declare function parsePositiveInt(value: string, flagName: string): number;
+/**
+ * Parse a single priority value (for `issues create --priority`, `issues update --priority`).
+ *
+ * Accepts:
+ *   - keywords:  none | urgent | high | medium | normal | low
+ *   - numbers:   0 (no priority), 1 (urgent), 2 (high), 3 (medium), 4 (low)
+ */
 export declare function validatePriority(value: string): number;
 export declare function validateHexColor(value: string): string;
 export declare function validateIsoDate(value: string): string;

package/dist/utils/validators.js

@@ -8,14 +8,21 @@ export function parsePositiveInt(value, flagName) {
     }
     return n;
 }
+/**
+ * Parse a single priority value (for `issues create --priority`, `issues update --priority`).
+ *
+ * Accepts:
+ *   - keywords:  none | urgent | high | medium | normal | low
+ *   - numbers:   0 (no priority), 1 (urgent), 2 (high), 3 (medium), 4 (low)
+ */
 export function validatePriority(value) {
     const asName = PRIORITY_NAMES[value.toLowerCase()];
-    if (asName !== undefined && asName >= 1) {
+    if (asName !== undefined) {
         return asName;
     }
     const n = Number.parseInt(value, 10);
-    if (Number.isNaN(n) || n < 1 || n > 4) {
-        throw invalidParameterError("--priority", `"${value}" is not valid. Use names (urgent, high, medium/normal, low) or numbers (1-4).`);
+    if (Number.isNaN(n) || n < 0 || n > 4) {
+        throw invalidParameterError("--priority", `"${value}" is not valid. Use names (none, urgent, high, medium/normal, low) or numbers (0-4).`);
     }
     return n;
 }
@@ -41,6 +48,9 @@ export function splitList(value) {
         .map((s) => s.trim())
         .filter((s) => s.length > 0);
 }
+// Shared keyword → Linear priority number map. `none` and `0` mean "No priority"
+// (Linear stores it as a real state, not absence). `1..4` are the rated priorities,
+// `urgent` (1) being the highest.
 const PRIORITY_NAMES = {
     none: 0,
     urgent: 1,
@@ -50,17 +60,7 @@ const PRIORITY_NAMES = {
     low: 4,
 };
 export function parsePriorityFilter(value) {
-    return splitList(value).map((item) => {
-        const asName = PRIORITY_NAMES[item.toLowerCase()];
-        if (asName !== undefined) {
-            return asName;
-        }
-        const n = Number.parseInt(item, 10);
-        if (Number.isNaN(n) || n < 0 || n > 4) {
-            throw invalidParameterError("--priority", `"${item}" is not valid. Use names (urgent, high, medium, low, none) or numbers (0-4).`);
-        }
-        return n;
-    });
+    return splitList(value).map((item) => validatePriority(item));
 }
 export const PRIORITY_LABELS = {
     0: "No priority",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enrichlayer/el-linear",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "A pragmatic CLI for Linear.app — deterministic team/label/member resolution, structured issue validation, configurable term enforcement, and a GraphQL escape hatch.",
   "main": "dist/main.js",
   "types": "dist/main.d.ts",