@enrichlayer/el-linear 1.2.0

package/dist/utils/output.js

@@ -0,0 +1,125 @@
+import { execFileSync } from "node:child_process";
+import { logger } from "./logger.js";
+const warningBuffer = [];
+let rawMode = false;
+let jqFilter = null;
+let fieldsFilter = null;
+export function setRawMode(enabled) {
+    rawMode = enabled;
+}
+export function setJqFilter(filter) {
+    jqFilter = filter;
+}
+export function setFieldsFilter(fields) {
+    fieldsFilter = fields;
+}
+function filterFields(obj, fields) {
+    if (Array.isArray(obj)) {
+        return obj.map((item) => filterFields(item, fields));
+    }
+    if (obj !== null && typeof obj === "object") {
+        const source = obj;
+        const result = {};
+        for (const field of fields) {
+            if (field in source) {
+                result[field] = source[field];
+            }
+        }
+        return result;
+    }
+    return obj;
+}
+export function outputSuccess(data) {
+    const warnings = drainWarnings();
+    let output;
+    if (warnings.length > 0 &&
+        data !== null &&
+        typeof data === "object" &&
+        !Array.isArray(data)) {
+        output = { ...data, _warnings: warnings };
+    }
+    else {
+        output = data;
+    }
+    // --raw: unwrap { data: [...] } to just the array
+    if (rawMode &&
+        output !== null &&
+        typeof output === "object" &&
+        !Array.isArray(output)) {
+        const obj = output;
+        if (Array.isArray(obj.data)) {
+            output = obj.data;
+        }
+    }
+    // --fields: filter object keys (applies to array items or flat objects)
+    if (fieldsFilter) {
+        if (Array.isArray(output)) {
+            output = filterFields(output, fieldsFilter);
+        }
+        else if (output !== null && typeof output === "object") {
+            const obj = output;
+            if (Array.isArray(obj.data)) {
+                output = { ...obj, data: filterFields(obj.data, fieldsFilter) };
+            }
+            else {
+                output = filterFields(output, fieldsFilter);
+            }
+        }
+    }
+    if (jqFilter) {
+        const json = JSON.stringify(output);
+        // Normalize common shell-escape artifacts (zsh history expansion)
+        const filter = jqFilter.replace(/\\!/g, "!");
+        try {
+            const result = execFileSync("jq", ["-r", filter], {
+                input: json,
+                encoding: "utf8",
+                maxBuffer: 10 * 1024 * 1024,
+            });
+            process.stdout.write(result);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new Error(`jq filter failed: ${msg}`);
+        }
+    }
+    else {
+        logger.info(JSON.stringify(output, null, 2));
+    }
+}
+export function outputWarning(message, _type) {
+    const messages = Array.isArray(message) ? message : [message];
+    for (const msg of messages) {
+        warningBuffer.push(msg);
+    }
+    // Warnings are buffered and embedded as _warnings in the next outputSuccess call.
+    // No stderr output — this prevents multi-JSON corruption when callers use 2>&1.
+}
+function drainWarnings() {
+    const warnings = [...warningBuffer];
+    warningBuffer.length = 0;
+    return warnings;
+}
+export function resetWarnings() {
+    warningBuffer.length = 0;
+}
+function outputError(error) {
+    const payload = JSON.stringify({ error: error.message }, null, 2);
+    // Write to stdout (same channel as success) so machine callers always
+    // receive exactly one parseable JSON object regardless of stream capture.
+    logger.info(payload);
+    if (process.env.EL_LINEAR_DEBUG ?? process.env.LINCTL_DEBUG) {
+        logger.error(error.stack ?? "");
+    }
+    process.exit(1);
+}
+export function handleAsyncCommand(asyncFn) {
+    return async (...args) => {
+        try {
+            await asyncFn(...args);
+        }
+        catch (error) {
+            outputError(error instanceof Error ? error : new Error(String(error)));
+        }
+    };
+}

package/dist/utils/table-formatter.d.ts

@@ -0,0 +1,4 @@
+import type { LinearIssue } from "../types/linear.js";
+export declare function formatTable(issues: LinearIssue[], fieldNames?: string[]): string;
+export declare function formatCsv(issues: LinearIssue[], fieldNames?: string[]): string;
+export declare function formatMarkdown(issues: LinearIssue[], fieldNames?: string[]): string;

package/dist/utils/table-formatter.js

@@ -0,0 +1,249 @@
+import pc from "picocolors";
+import { PRIORITY_LABELS } from "./validators.js";
+// ── Status colors ──────────────────────────────────────────────
+const STATUS_COLORS = {
+    triage: pc.magenta,
+    backlog: pc.dim,
+    todo: pc.white,
+    "in progress": pc.cyan,
+    "in review": pc.blue,
+    done: pc.green,
+    canceled: (s) => pc.dim(pc.strikethrough(s)),
+    cancelled: (s) => pc.dim(pc.strikethrough(s)),
+    duplicate: (s) => pc.dim(pc.strikethrough(s)),
+};
+function colorizeStatus(value) {
+    const fn = STATUS_COLORS[value.toLowerCase()];
+    return fn ? fn(value) : value;
+}
+// ── Priority formatting ────────────────────────────────────────
+const PRIORITY_PREFIX = {
+    0: "",
+    1: "▲▲▲ ",
+    2: "▲▲  ",
+    3: "▲   ",
+    4: "▽   ",
+};
+const PRIORITY_COLORS = {
+    0: pc.dim,
+    1: (s) => pc.red(pc.bold(s)),
+    2: pc.yellow,
+    3: pc.cyan,
+    4: pc.dim,
+};
+function extractPriority(issue) {
+    const label = PRIORITY_LABELS[issue.priority] ?? "—";
+    const prefix = PRIORITY_PREFIX[issue.priority] ?? "";
+    return `${prefix}${label}`;
+}
+function colorizePriority(value, issue) {
+    const fn = PRIORITY_COLORS[issue.priority];
+    return fn ? fn(value) : value;
+}
+// ── Hyperlinks ─────────────────────────────────────────────────
+function hyperlink(text, url) {
+    return `\x1b]8;;${url}\x1b\\${text}\x1b]8;;\x1b\\`;
+}
+// ── Column definitions ─────────────────────────────────────────
+const ALL_COLUMNS = {
+    identifier: {
+        key: "identifier",
+        header: "ID",
+        width: 10,
+        extract: (i) => i.identifier,
+        colorize: (value, issue) => hyperlink(value, issue.url),
+    },
+    title: {
+        key: "title",
+        header: "Title",
+        width: 55,
+        extract: (i) => i.title,
+    },
+    status: {
+        key: "status",
+        header: "Status",
+        width: 14,
+        extract: (i) => i.state?.name ?? "—",
+        colorize: (v) => colorizeStatus(v),
+    },
+    priority: {
+        key: "priority",
+        header: "Priority",
+        width: 16,
+        extract: extractPriority,
+        colorize: colorizePriority,
+    },
+    assignee: {
+        key: "assignee",
+        header: "Assignee",
+        width: 20,
+        extract: (i) => {
+            if (!i.assignee) {
+                return "—";
+            }
+            const name = i.assignee.name;
+            const atIdx = name.indexOf("@");
+            return atIdx > 0 ? name.slice(0, atIdx) : name;
+        },
+    },
+    project: {
+        key: "project",
+        header: "Project",
+        width: 28,
+        extract: (i) => i.project?.name ?? "—",
+    },
+    team: {
+        key: "team",
+        header: "Team",
+        width: 6,
+        extract: (i) => i.team?.key ?? "—",
+    },
+    labels: {
+        key: "labels",
+        header: "Labels",
+        width: 25,
+        extract: (i) => i.labels.map((l) => l.name).join(", ") || "—",
+    },
+    updated: {
+        key: "updated",
+        header: "Updated",
+        width: 12,
+        extract: (i) => i.updatedAt.slice(0, 10),
+    },
+};
+const DEFAULT_COLUMNS = [
+    "identifier",
+    "title",
+    "status",
+    "priority",
+    "assignee",
+    "project",
+];
+function truncate(str, maxLen) {
+    if (str.length <= maxLen) {
+        return str;
+    }
+    return `${str.slice(0, maxLen - 1)}…`;
+}
+function pad(str, width) {
+    const truncated = truncate(str, width);
+    return truncated + " ".repeat(Math.max(0, width - truncated.length));
+}
+export function formatTable(issues, fieldNames) {
+    const columnKeys = fieldNames ?? DEFAULT_COLUMNS;
+    const columns = columnKeys
+        .map((key) => ALL_COLUMNS[key])
+        .filter((col) => col !== undefined);
+    if (columns.length === 0) {
+        return "No valid columns specified.";
+    }
+    const header = columns.map((col) => pad(col.header, col.width)).join("  ");
+    const separator = columns.map((col) => "─".repeat(col.width)).join("──");
+    const rows = issues.map((issue) => columns
+        .map((col) => {
+        const padded = pad(col.extract(issue), col.width);
+        return col.colorize ? col.colorize(padded, issue) : padded;
+    })
+        .join("  "));
+    return [header, separator, ...rows].join("\n");
+}
+export function formatCsv(issues, fieldNames) {
+    const columnKeys = fieldNames ?? DEFAULT_COLUMNS;
+    const columns = columnKeys
+        .map((key) => ALL_COLUMNS[key])
+        .filter((col) => col !== undefined);
+    const header = columns.map((col) => col.header).join(",");
+    const rows = issues.map((issue) => columns
+        .map((col) => {
+        const value = col.extract(issue);
+        return value.includes(",") || value.includes('"')
+            ? `"${value.replace(/"/g, '""')}"`
+            : value;
+    })
+        .join(","));
+    return [header, ...rows].join("\n");
+}
+// ── Markdown formatting ────────────────────────────────────────
+const STATUS_MD = {
+    triage: (s) => `**${s}**`,
+    backlog: (s) => s,
+    todo: (s) => s,
+    "in progress": (s) => `**${s}**`,
+    "in review": (s) => `*${s}*`,
+    done: (s) => `~~${s}~~`,
+    canceled: (s) => `~~${s}~~`,
+    cancelled: (s) => `~~${s}~~`,
+    duplicate: (s) => `~~${s}~~`,
+};
+const PRIORITY_MD = {
+    0: "—",
+    1: "**‼ Urgent**",
+    2: "**! High**",
+    3: "Medium",
+    4: "Low",
+};
+const MD_COLUMNS = {
+    identifier: {
+        header: "Issue",
+        extract: (i) => `[${i.identifier}](${i.url})`,
+    },
+    title: {
+        header: "Title",
+        extract: (i) => i.title,
+    },
+    status: {
+        header: "Status",
+        extract: (i) => {
+            const name = i.state?.name ?? "—";
+            const fn = STATUS_MD[name.toLowerCase()];
+            return fn ? fn(name) : name;
+        },
+    },
+    priority: {
+        header: "Priority",
+        extract: (i) => PRIORITY_MD[i.priority] ?? "—",
+    },
+    assignee: {
+        header: "Assignee",
+        extract: (i) => {
+            if (!i.assignee) {
+                return "—";
+            }
+            const name = i.assignee.name;
+            const atIdx = name.indexOf("@");
+            return atIdx > 0 ? name.slice(0, atIdx) : name;
+        },
+    },
+    project: {
+        header: "Project",
+        extract: (i) => i.project?.name ?? "—",
+    },
+    team: {
+        header: "Team",
+        extract: (i) => i.team?.key ?? "—",
+    },
+    labels: {
+        header: "Labels",
+        extract: (i) => i.labels.map((l) => l.name).join(", ") || "—",
+    },
+    updated: {
+        header: "Updated",
+        extract: (i) => i.updatedAt.slice(0, 10),
+    },
+};
+function escapeMarkdownCell(str) {
+    return str.replace(/\|/g, "\\|").replace(/\n/g, " ");
+}
+export function formatMarkdown(issues, fieldNames) {
+    const columnKeys = fieldNames ?? DEFAULT_COLUMNS;
+    const columns = columnKeys
+        .map((key) => MD_COLUMNS[key])
+        .filter((col) => col !== undefined);
+    if (columns.length === 0) {
+        return "No valid columns specified.";
+    }
+    const header = `| ${columns.map((col) => col.header).join(" | ")} |`;
+    const divider = `| ${columns.map((col) => (col.align === "right" ? "---:" : "---")).join(" | ")} |`;
+    const rows = issues.map((issue) => `| ${columns.map((col) => escapeMarkdownCell(col.extract(issue))).join(" | ")} |`);
+    return [header, divider, ...rows].join("\n");
+}

package/dist/utils/usage.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function outputUsageInfo(program: Command): void;

package/dist/utils/usage.js

@@ -0,0 +1,24 @@
+import { logger } from "./logger.js";
+export function outputUsageInfo(program) {
+    const subcommands = [];
+    function collectSubcommands(cmd, prefix = "") {
+        const currentName = prefix ? `${prefix} ${cmd.name()}` : cmd.name();
+        const commands = cmd.commands;
+        if (commands.length === 0) {
+            if (prefix) {
+                subcommands.push({ name: currentName, command: cmd });
+            }
+        }
+        else {
+            for (const subcmd of commands) {
+                collectSubcommands(subcmd, currentName);
+            }
+        }
+    }
+    collectSubcommands(program);
+    subcommands.sort((a, b) => a.name.localeCompare(b.name));
+    for (const { command } of subcommands) {
+        command.outputHelp();
+        logger.info("\n---\n");
+    }
+}

package/dist/utils/uuid.d.ts

@@ -0,0 +1,2 @@
+export declare function isUuid(value: string): boolean;
+export declare function isUuidPrefix(value: string): boolean;

package/dist/utils/uuid.js

@@ -0,0 +1,8 @@
+const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const UUID_PREFIX_REGEX = /^[0-9a-f]{8}$/i;
+export function isUuid(value) {
+    return UUID_REGEX.test(value);
+}
+export function isUuidPrefix(value) {
+    return UUID_PREFIX_REGEX.test(value);
+}

package/dist/utils/validate-references.d.ts

@@ -0,0 +1,10 @@
+import type { LinearService } from "./linear-service.js";
+/**
+ * Resolve each candidate identifier to its UUID. Returns a map containing only
+ * identifiers that resolved successfully — non-existent IDs (e.g. "ISO-1424"
+ * false positives, or refs to issues outside the workspace) are dropped silently.
+ *
+ * Resolutions run in parallel for throughput. The map preserves the order of
+ * the input array via insertion order on the underlying Map.
+ */
+export declare function validateReferences(identifiers: readonly string[], linearService: LinearService): Promise<Map<string, string>>;

package/dist/utils/validate-references.js

@@ -0,0 +1,33 @@
+/**
+ * Resolve each candidate identifier to its UUID. Returns a map containing only
+ * identifiers that resolved successfully — non-existent IDs (e.g. "ISO-1424"
+ * false positives, or refs to issues outside the workspace) are dropped silently.
+ *
+ * Resolutions run in parallel for throughput. The map preserves the order of
+ * the input array via insertion order on the underlying Map.
+ */
+export async function validateReferences(identifiers, linearService) {
+    const valid = new Map();
+    if (identifiers.length === 0) {
+        return valid;
+    }
+    // Deduplicate while preserving order.
+    const seen = new Set();
+    const unique = identifiers.filter((id) => {
+        if (seen.has(id)) {
+            return false;
+        }
+        seen.add(id);
+        return true;
+    });
+    const settled = await Promise.allSettled(unique.map(async (id) => ({
+        id,
+        uuid: await linearService.resolveIssueId(id),
+    })));
+    for (const result of settled) {
+        if (result.status === "fulfilled") {
+            valid.set(result.value.id, result.value.uuid);
+        }
+    }
+    return valid;
+}

package/dist/utils/validators.d.ts

@@ -0,0 +1,7 @@
+export declare function parsePositiveInt(value: string, flagName: string): number;
+export declare function validatePriority(value: string): number;
+export declare function validateHexColor(value: string): string;
+export declare function validateIsoDate(value: string): string;
+export declare function splitList(value: string): string[];
+export declare function parsePriorityFilter(value: string): number[];
+export declare const PRIORITY_LABELS: Record<number, string>;

package/dist/utils/validators.js

@@ -0,0 +1,71 @@
+import { invalidParameterError } from "./error-messages.js";
+const HEX_COLOR_RE = /^#[0-9a-fA-F]{6}$/;
+const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+export function parsePositiveInt(value, flagName) {
+    const n = Number.parseInt(value, 10);
+    if (Number.isNaN(n) || n < 1) {
+        throw invalidParameterError(flagName, `"${value}" is not a positive integer`);
+    }
+    return n;
+}
+export function validatePriority(value) {
+    const asName = PRIORITY_NAMES[value.toLowerCase()];
+    if (asName !== undefined && asName >= 1) {
+        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).`);
+    }
+    return n;
+}
+export function validateHexColor(value) {
+    if (!HEX_COLOR_RE.test(value)) {
+        throw invalidParameterError("--color", `"${value}" is not a valid hex color. Use #RRGGBB format (e.g. #e06666).`);
+    }
+    return value;
+}
+export function validateIsoDate(value) {
+    if (!ISO_DATE_RE.test(value)) {
+        throw invalidParameterError("--target-date", `"${value}" is not a valid date. Use YYYY-MM-DD format.`);
+    }
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime())) {
+        throw invalidParameterError("--target-date", `"${value}" is not a valid date.`);
+    }
+    return value;
+}
+export function splitList(value) {
+    return value
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+const PRIORITY_NAMES = {
+    none: 0,
+    urgent: 1,
+    high: 2,
+    medium: 3,
+    normal: 3,
+    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;
+    });
+}
+export const PRIORITY_LABELS = {
+    0: "No priority",
+    1: "Urgent",
+    2: "High",
+    3: "Medium",
+    4: "Low",
+};

package/dist/utils/workspace-url.d.ts

@@ -0,0 +1,4 @@
+import type { GraphQLService } from "./graphql-service.js";
+export declare function getWorkspaceUrlKey(graphQLService: GraphQLService): Promise<string>;
+/** Test helper: clear the cached URL key. Not called from production code. */
+export declare function _resetWorkspaceUrlKeyCache(): void;

package/dist/utils/workspace-url.js

@@ -0,0 +1,44 @@
+import { loadConfig } from "../config/config.js";
+/**
+ * Resolve the Linear workspace URL key (the segment after `linear.app/` in
+ * issue URLs). Used to build canonical markdown link URLs like
+ * `https://linear.app/<urlKey>/issue/<identifier>/`.
+ *
+ * Resolution order:
+ *   1. `config.workspaceUrlKey` if explicitly set in el-linear config
+ *   2. `viewer.organization.urlKey` from the Linear API (fetched once, cached)
+ *
+ * Cached in-process for the lifetime of the CLI invocation.
+ */
+const VIEWER_ORG_URL_KEY_QUERY = /* GraphQL */ `
+  query ViewerOrgUrlKey {
+    viewer {
+      organization {
+        urlKey
+      }
+    }
+  }
+`;
+let cachedUrlKey;
+export async function getWorkspaceUrlKey(graphQLService) {
+    if (cachedUrlKey) {
+        return cachedUrlKey;
+    }
+    const { workspaceUrlKey } = loadConfig();
+    if (workspaceUrlKey) {
+        cachedUrlKey = workspaceUrlKey;
+        return workspaceUrlKey;
+    }
+    const data = await graphQLService.rawRequest(VIEWER_ORG_URL_KEY_QUERY);
+    const fetched = data?.viewer?.organization?.urlKey;
+    if (!fetched) {
+        throw new Error("Could not resolve Linear workspace URL key from `viewer.organization.urlKey`. " +
+            "Set `workspaceUrlKey` in your el-linear config to override.");
+    }
+    cachedUrlKey = fetched;
+    return fetched;
+}
+/** Test helper: clear the cached URL key. Not called from production code. */
+export function _resetWorkspaceUrlKeyCache() {
+    cachedUrlKey = undefined;
+}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@enrichlayer/el-linear",
+  "version": "1.2.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",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/main.d.ts",
+      "import": "./dist/main.js"
+    }
+  },
+  "sideEffects": false,
+  "bin": {
+    "el-linear": "dist/main.js"
+  },
+  "files": [
+    "dist/",
+    "claude-skills/",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/enrichlayer/el-linear.git"
+  },
+  "homepage": "https://enrichlayer.com/tools/el-linear",
+  "bugs": {
+    "url": "https://github.com/enrichlayer/el-linear/issues"
+  },
+  "keywords": [
+    "linear",
+    "linear.app",
+    "cli",
+    "issue-tracker",
+    "graphql",
+    "claude",
+    "claude-code"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^8.4.2",
+    "@linear/sdk": "^83.0.0",
+    "commander": "^14.0.0",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.0",
+    "@types/node": "^25.0.0",
+    "graphql": "^16.0.0",
+    "tsx": "^4.20.5",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsc && chmod +x dist/main.js",
+    "clean": "rm -rf dist/",
+    "lint": "biome check .",
+    "lint:fix": "biome check --fix .",
+    "start": "tsx src/main.ts",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}