linear-cli-agents 0.1.0

package/dist/lib/config.js

@@ -0,0 +1,97 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, unlinkSync } from 'node:fs';
+import { CliError, ErrorCodes } from './errors.js';
+const CONFIG_DIR = join(homedir(), '.linear-cli');
+const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+/**
+ * Ensure the config directory exists.
+ */
+const ensureConfigDir = () => {
+    if (!existsSync(CONFIG_DIR)) {
+        mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    }
+};
+/**
+ * Read the configuration file.
+ * @throws {CliError} When config file exists but cannot be parsed.
+ */
+export const readConfig = () => {
+    if (!existsSync(CONFIG_FILE)) {
+        return {};
+    }
+    try {
+        const content = readFileSync(CONFIG_FILE, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            throw new CliError(ErrorCodes.CONFIG_ERROR, `Failed to parse config file at ${CONFIG_FILE}. Please check the file format or delete it.`, { path: CONFIG_FILE });
+        }
+        throw error;
+    }
+};
+/**
+ * Write the configuration file atomically.
+ * Uses a temp file + rename to prevent corruption.
+ */
+export const writeConfig = (config) => {
+    ensureConfigDir();
+    const tempFile = join(CONFIG_DIR, `config.json.tmp.${Date.now()}`);
+    try {
+        writeFileSync(tempFile, JSON.stringify(config, null, 2), { mode: 0o600 });
+        renameSync(tempFile, CONFIG_FILE);
+    }
+    catch (error) {
+        try {
+            unlinkSync(tempFile);
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+        throw new CliError(ErrorCodes.CONFIG_ERROR, `Failed to write config: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+};
+/**
+ * Get the API key from config or environment.
+ * Environment variable LINEAR_API_KEY takes precedence.
+ */
+export const getApiKey = () => {
+    const envKey = process.env.LINEAR_API_KEY;
+    if (envKey) {
+        return envKey;
+    }
+    const config = readConfig();
+    return config.apiKey;
+};
+/**
+ * Get the API key or throw if not configured.
+ * @throws {CliError} When no API key is configured (NOT_AUTHENTICATED).
+ */
+export const requireApiKey = () => {
+    const apiKey = getApiKey();
+    if (!apiKey) {
+        throw new CliError(ErrorCodes.NOT_AUTHENTICATED, 'Not authenticated. Run "linear auth login" or set LINEAR_API_KEY environment variable.');
+    }
+    return apiKey;
+};
+/**
+ * Save the API key to config with secure permissions.
+ */
+export const saveApiKey = (apiKey) => {
+    const config = readConfig();
+    config.apiKey = apiKey;
+    writeConfig(config);
+};
+/**
+ * Remove the API key from config.
+ */
+export const removeApiKey = () => {
+    const config = readConfig();
+    delete config.apiKey;
+    writeConfig(config);
+};
+/**
+ * Get the config file path (for display purposes).
+ */
+export const getConfigPath = () => CONFIG_FILE;

package/dist/lib/errors.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Standard error codes for the CLI.
+ */
+export declare const ErrorCodes: {
+    readonly NOT_AUTHENTICATED: "NOT_AUTHENTICATED";
+    readonly INVALID_API_KEY: "INVALID_API_KEY";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly ALREADY_EXISTS: "ALREADY_EXISTS";
+    readonly INVALID_INPUT: "INVALID_INPUT";
+    readonly MISSING_REQUIRED_FIELD: "MISSING_REQUIRED_FIELD";
+    readonly API_ERROR: "API_ERROR";
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    readonly CONFIG_ERROR: "CONFIG_ERROR";
+    readonly UNKNOWN_ERROR: "UNKNOWN_ERROR";
+};
+export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+/**
+ * CLI-specific error class that produces structured JSON output.
+ */
+export declare class CliError extends Error {
+    readonly code: ErrorCode;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(code: ErrorCode, message: string, details?: Record<string, unknown> | undefined);
+    toResponse(): import("./types.js").ErrorResponse;
+    print(): void;
+}
+/**
+ * Handle any error and convert to structured output.
+ */
+export declare const handleError: (err: unknown) => void;

package/dist/lib/errors.js

@@ -0,0 +1,79 @@
+import { error, print } from './output.js';
+/**
+ * Standard error codes for the CLI.
+ */
+export const ErrorCodes = {
+    // Auth errors
+    NOT_AUTHENTICATED: 'NOT_AUTHENTICATED',
+    INVALID_API_KEY: 'INVALID_API_KEY',
+    // Resource errors
+    NOT_FOUND: 'NOT_FOUND',
+    ALREADY_EXISTS: 'ALREADY_EXISTS',
+    // Validation errors
+    INVALID_INPUT: 'INVALID_INPUT',
+    MISSING_REQUIRED_FIELD: 'MISSING_REQUIRED_FIELD',
+    // API errors
+    API_ERROR: 'API_ERROR',
+    RATE_LIMITED: 'RATE_LIMITED',
+    // System errors
+    CONFIG_ERROR: 'CONFIG_ERROR',
+    UNKNOWN_ERROR: 'UNKNOWN_ERROR',
+};
+/**
+ * CLI-specific error class that produces structured JSON output.
+ */
+export class CliError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = 'CliError';
+    }
+    toResponse() {
+        return error(this.code, this.message, this.details);
+    }
+    print() {
+        print(this.toResponse());
+    }
+}
+/**
+ * Map error message patterns to structured error responses.
+ */
+const ERROR_PATTERNS = [
+    {
+        test: (msg) => msg.includes('401') || msg.includes('Unauthorized'),
+        code: ErrorCodes.INVALID_API_KEY,
+        message: 'Invalid or expired API key',
+    },
+    {
+        test: (msg) => msg.includes('404') || msg.includes('not found'),
+        code: ErrorCodes.NOT_FOUND,
+        message: null,
+    },
+    {
+        test: (msg) => msg.includes('429') || msg.includes('rate limit'),
+        code: ErrorCodes.RATE_LIMITED,
+        message: 'Rate limit exceeded. Please wait before retrying.',
+    },
+];
+/**
+ * Handle any error and convert to structured output.
+ */
+export const handleError = (err) => {
+    if (err instanceof CliError) {
+        err.print();
+        return;
+    }
+    if (err instanceof Error) {
+        const matched = ERROR_PATTERNS.find((pattern) => pattern.test(err.message));
+        if (matched) {
+            print(error(matched.code, matched.message ?? err.message));
+            return;
+        }
+        print(error(ErrorCodes.API_ERROR, err.message));
+        return;
+    }
+    print(error(ErrorCodes.UNKNOWN_ERROR, 'An unexpected error occurred'));
+};

package/dist/lib/issue-utils.d.ts

@@ -0,0 +1,17 @@
+import type { LinearClient } from '@linear/sdk';
+/**
+ * Parse an issue identifier (e.g., ENG-123) into team key and number.
+ */
+export declare const parseIdentifier: (identifier: string) => {
+    teamKey: string;
+    number: number;
+} | null;
+/**
+ * Check if a string is a UUID (issue ID).
+ */
+export declare const isUUID: (str: string) => boolean;
+/**
+ * Resolve an issue identifier or ID to an issue ID.
+ * Supports both UUIDs and identifiers like ENG-123.
+ */
+export declare const resolveIssueId: (client: LinearClient, idOrIdentifier: string) => Promise<string>;

package/dist/lib/issue-utils.js

@@ -0,0 +1,56 @@
+import { CliError, ErrorCodes } from './errors.js';
+/**
+ * Parse an issue identifier (e.g., ENG-123) into team key and number.
+ */
+export const parseIdentifier = (identifier) => {
+    const match = identifier.match(/^([A-Za-z]+)-(\d+)$/);
+    if (!match) {
+        return null;
+    }
+    return {
+        teamKey: match[1].toUpperCase(),
+        number: parseInt(match[2], 10),
+    };
+};
+/**
+ * Check if a string is a UUID (issue ID).
+ */
+export const isUUID = (str) => {
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(str);
+};
+/**
+ * Resolve an issue identifier or ID to an issue ID.
+ * Supports both UUIDs and identifiers like ENG-123.
+ */
+export const resolveIssueId = async (client, idOrIdentifier) => {
+    // If it's a UUID, return as-is
+    if (isUUID(idOrIdentifier)) {
+        return idOrIdentifier;
+    }
+    // Try to parse as identifier
+    const parsed = parseIdentifier(idOrIdentifier);
+    if (!parsed) {
+        throw new CliError(ErrorCodes.INVALID_INPUT, `Invalid issue ID or identifier: ${idOrIdentifier}. Expected UUID or format like ENG-123.`);
+    }
+    // Find the team by key
+    const teams = await client.teams({
+        filter: { key: { eq: parsed.teamKey } },
+        first: 1,
+    });
+    if (teams.nodes.length === 0) {
+        throw new CliError(ErrorCodes.NOT_FOUND, `Team with key "${parsed.teamKey}" not found`);
+    }
+    const team = teams.nodes[0];
+    // Find the issue by team and number
+    const issues = await client.issues({
+        filter: {
+            team: { id: { eq: team.id } },
+            number: { eq: parsed.number },
+        },
+        first: 1,
+    });
+    if (issues.nodes.length === 0) {
+        throw new CliError(ErrorCodes.NOT_FOUND, `Issue ${idOrIdentifier} not found`);
+    }
+    return issues.nodes[0].id;
+};

package/dist/lib/output.d.ts

@@ -0,0 +1,16 @@
+import type { CommandResponse, CommandListResponse, PageInfo, ErrorResponse } from './types.js';
+/**
+ * Output utilities for consistent JSON formatting.
+ * All CLI output goes through these functions for parseable responses.
+ */
+export declare const success: <T>(data: T) => CommandResponse<T>;
+export declare const successList: <T>(data: T[], pageInfo?: PageInfo) => CommandListResponse<T>;
+export declare const error: (code: string, message: string, details?: Record<string, unknown>) => ErrorResponse;
+/**
+ * Print a response as formatted JSON to stdout.
+ */
+export declare const print: <T>(response: CommandResponse<T> | CommandListResponse<T>) => void;
+/**
+ * Print raw data as formatted JSON to stdout.
+ */
+export declare const printRaw: (data: unknown) => void;

package/dist/lib/output.js

@@ -0,0 +1,33 @@
+/**
+ * Output utilities for consistent JSON formatting.
+ * All CLI output goes through these functions for parseable responses.
+ */
+export const success = (data) => ({
+    success: true,
+    data,
+});
+export const successList = (data, pageInfo) => ({
+    success: true,
+    data,
+    ...(pageInfo && { pageInfo }),
+});
+export const error = (code, message, details) => ({
+    success: false,
+    error: {
+        code,
+        message,
+        ...(details && { details }),
+    },
+});
+/**
+ * Print a response as formatted JSON to stdout.
+ */
+export const print = (response) => {
+    console.log(JSON.stringify(response, null, 2));
+};
+/**
+ * Print raw data as formatted JSON to stdout.
+ */
+export const printRaw = (data) => {
+    console.log(JSON.stringify(data, null, 2));
+};

package/dist/lib/types.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Standard output types for all CLI commands.
+ * All outputs are JSON-formatted for easy parsing by LLMs.
+ */
+export interface PageInfo {
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+    startCursor?: string;
+    endCursor?: string;
+}
+export interface SuccessResponse<T> {
+    success: true;
+    data: T;
+}
+export interface SuccessListResponse<T> {
+    success: true;
+    data: T[];
+    pageInfo?: PageInfo;
+}
+export interface ErrorResponse {
+    success: false;
+    error: {
+        code: string;
+        message: string;
+        details?: Record<string, unknown>;
+    };
+}
+export type CommandResponse<T> = SuccessResponse<T> | ErrorResponse;
+export type CommandListResponse<T> = SuccessListResponse<T> | ErrorResponse;
+export interface ConfigFile {
+    apiKey?: string;
+    defaultTeamId?: string;
+}

package/dist/lib/types.js

@@ -0,0 +1,5 @@
+/**
+ * Standard output types for all CLI commands.
+ * All outputs are JSON-formatted for easy parsing by LLMs.
+ */
+export {};