@hasna/connectors 0.3.16 → 0.4.0

package/connectors/connect-jira/src/utils/output.ts

@@ -0,0 +1,119 @@
+import chalk from 'chalk';
+
+export type OutputFormat = 'json' | 'table' | 'pretty';
+
+export function formatOutput(data: unknown, format: OutputFormat = 'pretty'): string {
+  switch (format) {
+    case 'json':
+      return JSON.stringify(data, null, 2);
+    case 'table':
+      return formatAsTable(data);
+    case 'pretty':
+    default:
+      return formatPretty(data);
+  }
+}
+
+function formatAsTable(data: unknown): string {
+  if (!Array.isArray(data)) {
+    data = [data];
+  }
+
+  const items = data as Record<string, unknown>[];
+  if (items.length === 0) {
+    return 'No data';
+  }
+
+  const firstItem = items[0];
+  if (!firstItem || typeof firstItem !== 'object') {
+    return 'No data';
+  }
+
+  const keys = Object.keys(firstItem);
+  const colWidths = keys.map(key => {
+    const maxValue = Math.max(
+      key.length,
+      ...items.map(item => String(item[key] ?? '').length)
+    );
+    return Math.min(maxValue, 40);
+  });
+
+  const header = keys.map((key, i) => key.padEnd(colWidths[i] ?? 10)).join(' | ');
+  const separator = colWidths.map(w => '-'.repeat(w)).join('-+-');
+
+  const rows = items.map(item =>
+    keys.map((key, i) => {
+      const value = String(item[key] ?? '');
+      const width = colWidths[i] ?? 10;
+      return value.length > width
+        ? value.substring(0, width - 3) + '...'
+        : value.padEnd(width);
+    }).join(' | ')
+  );
+
+  return [header, separator, ...rows].join('\n');
+}
+
+function formatPretty(data: unknown): string {
+  if (Array.isArray(data)) {
+    return data.map((item, i) => `${chalk.cyan(`[${i + 1}]`)} ${formatPrettyItem(item)}`).join('\n\n');
+  }
+  return formatPrettyItem(data);
+}
+
+function formatPrettyItem(item: unknown, indent = 0): string {
+  if (item === null || item === undefined) {
+    return chalk.gray('null');
+  }
+
+  if (typeof item !== 'object') {
+    return String(item);
+  }
+
+  const spaces = '  '.repeat(indent);
+  const entries = Object.entries(item as Record<string, unknown>);
+
+  return entries
+    .map(([key, value]) => {
+      if (Array.isArray(value)) {
+        if (value.length === 0) {
+          return `${spaces}${chalk.blue(key)}: ${chalk.gray('[]')}`;
+        }
+        if (typeof value[0] === 'object') {
+          return `${spaces}${chalk.blue(key)}:\n${value.map(v => formatPrettyItem(v, indent + 1)).join('\n')}`;
+        }
+        return `${spaces}${chalk.blue(key)}: ${value.join(', ')}`;
+      }
+
+      if (typeof value === 'object' && value !== null) {
+        return `${spaces}${chalk.blue(key)}:\n${formatPrettyItem(value, indent + 1)}`;
+      }
+
+      return `${spaces}${chalk.blue(key)}: ${chalk.white(String(value))}`;
+    })
+    .join('\n');
+}
+
+export function success(message: string): void {
+  console.log(chalk.green('✓'), message);
+}
+
+export function error(message: string): void {
+  console.error(chalk.red('✗'), message);
+}
+
+export function warn(message: string): void {
+  console.warn(chalk.yellow('⚠'), message);
+}
+
+export function info(message: string): void {
+  console.log(chalk.blue('ℹ'), message);
+}
+
+export function heading(message: string): void {
+  console.log(chalk.bold.cyan(`\n${message}\n`));
+}
+
+export function print(data: unknown, format: OutputFormat = 'pretty'): void {
+  console.log(formatOutput(data, format));
+}

package/connectors/connect-jira/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["bun-types"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "bin"]
+}

package/connectors/connect-linear/CLAUDE.md

@@ -0,0 +1,88 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with this repository.
+
+## Project Overview
+
+connect-linear is a TypeScript CLI and library for Linear's GraphQL API. It provides issue management, project management, team operations, and user operations with multi-profile support for managing multiple Linear workspaces.
+
+## Build & Run Commands
+
+```bash
+bun install           # Install dependencies
+bun run dev           # Run CLI in development
+bun run build         # Build for distribution
+bun run typecheck     # Type check
+```
+
+## Code Style
+
+- TypeScript with strict mode
+- ESM modules (type: module)
+- Async/await for all async operations
+- Minimal dependencies: commander, chalk
+
+## Project Structure
+
+```
+src/
+├── api/
+│   ├── client.ts     # GraphQL client with Bearer auth
+│   ├── issues.ts     # Issues API
+│   ├── projects.ts   # Projects API
+│   ├── teams.ts      # Teams API
+│   ├── users.ts      # Users API
+│   └── index.ts      # Main Linear class
+├── cli/
+│   └── index.ts      # CLI commands
+├── types/
+│   └── index.ts      # TypeScript types
+├── utils/
+│   ├── config.ts     # Multi-profile configuration
+│   └── output.ts     # CLI output formatting
+└── index.ts          # Library exports
+```
+
+## API Architecture
+
+The Linear API uses GraphQL. The client architecture:
+
+1. `LinearClient` - Base GraphQL client that handles authentication and requests
+2. API modules (Issues, Projects, Teams, Users) - Use the client to make specific queries/mutations
+3. `Linear` class - Main entry point that combines all API modules
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `LINEAR_API_KEY` | Linear API key |
+
+## Multi-Profile Configuration
+
+Configuration stored in `~/.connect/connect-linear/`:
+
+```
+~/.connect/connect-linear/
+├── current_profile
+└── profiles/
+    └── default/
+        └── config.json
+```
+
+## GraphQL Endpoint
+
+- Base URL: https://api.linear.app/graphql
+- Auth: Bearer token (API key sent directly as Authorization header)
+
+## Dependencies
+
+- commander: CLI framework
+- chalk: Terminal styling
+
+## Priority Values
+
+- 0: No priority
+- 1: Urgent
+- 2: High
+- 3: Normal
+- 4: Low

package/connectors/connect-linear/README.md

@@ -0,0 +1,201 @@
+# @hasna/connect-linear
+
+Linear API connector with CLI and library support. Provides a TypeScript-first interface for interacting with the Linear GraphQL API.
+
+## Installation
+
+```bash
+npm install @hasna/connect-linear
+# or
+bun add @hasna/connect-linear
+```
+
+For CLI usage, install globally:
+
+```bash
+npm install -g @hasna/connect-linear
+```
+
+## Configuration
+
+### Environment Variable
+
+Set your Linear API key as an environment variable:
+
+```bash
+export LINEAR_API_KEY="lin_api_xxxxx"
+```
+
+### CLI Configuration
+
+Or use the CLI to save your API key:
+
+```bash
+connect-linear config set-api-key lin_api_xxxxx
+```
+
+Configuration is stored in `~/.connect/connect-linear/`.
+
+## CLI Usage
+
+### Authentication
+
+```bash
+# Test authentication
+connect-linear test
+
+# Show current user
+connect-linear whoami
+```
+
+### Issues
+
+```bash
+# List issues
+connect-linear issues list
+connect-linear issues list --team <team-id>
+connect-linear issues list --project <project-id>
+connect-linear issues list --assignee <user-id>
+
+# Get issue details
+connect-linear issues get <issue-id>
+
+# Create issue
+connect-linear issues create --title "Bug fix" --team <team-id>
+connect-linear issues create --title "Feature" --team <team-id> --description "Details here" --priority 2
+
+# Update issue
+connect-linear issues update <issue-id> --title "New title"
+connect-linear issues update <issue-id> --state <state-id>
+connect-linear issues update <issue-id> --assignee <user-id>
+
+# Archive issue
+connect-linear issues archive <issue-id>
+
+# Search issues
+connect-linear issues search "bug"
+```
+
+### Projects
+
+```bash
+# List projects
+connect-linear projects list
+
+# Get project details
+connect-linear projects get <project-id>
+```
+
+### Teams
+
+```bash
+# List teams
+connect-linear teams list
+
+# Get team details
+connect-linear teams get <team-id>
+
+# List workflow states for a team
+connect-linear teams states <team-id>
+```
+
+### Users
+
+```bash
+# List users
+connect-linear users list
+connect-linear users list --all  # Include inactive users
+
+# Get user details
+connect-linear users get <user-id>
+
+# Current user
+connect-linear users me
+```
+
+### Multi-Profile Support
+
+```bash
+# Create a profile
+connect-linear profile create work
+
+# Switch profiles
+connect-linear profile use work
+
+# List profiles
+connect-linear profile list
+
+# Use profile for a single command
+connect-linear --profile work issues list
+```
+
+### Output Formats
+
+```bash
+# JSON output
+connect-linear issues list --format json
+
+# Table output
+connect-linear issues list --format table
+
+# Pretty output (default)
+connect-linear issues list --format pretty
+```
+
+## Library Usage
+
+```typescript
+import { Linear } from '@hasna/connect-linear';
+
+const linear = new Linear({
+  apiKey: process.env.LINEAR_API_KEY!,
+});
+
+// List issues
+const issues = await linear.issues.list({ teamId: 'team-id' });
+
+// Create issue
+const issue = await linear.issues.create({
+  title: 'New feature',
+  teamId: 'team-id',
+  description: 'Feature description',
+  priority: 2,
+});
+
+// Update issue
+await linear.issues.update(issue.id, {
+  stateId: 'done-state-id',
+});
+
+// Get current user
+const me = await linear.users.me();
+
+// List teams
+const teams = await linear.teams.list();
+
+// Get workflow states
+const states = await linear.teams.getWorkflowStates('team-id');
+
+// Search issues
+const results = await linear.issues.search('bug');
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `LINEAR_API_KEY` | Linear API key (required) |
+
+## Priority Values
+
+| Value | Label |
+|-------|-------|
+| 0 | No priority |
+| 1 | Urgent |
+| 2 | High |
+| 3 | Normal |
+| 4 | Low |
+
+## License
+
+Apache-2.0

package/connectors/connect-linear/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@hasna/connect-linear",
+  "version": "0.0.1",
+  "description": "Linear API connector with CLI and library support",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "connect-linear": "bin/index.js"
+  },
+  "scripts": {
+    "dev": "bun run ./src/cli/index.ts",
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun && bun build ./src/cli/index.ts --outdir ./bin --target bun",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "linear",
+    "api",
+    "cli",
+    "connector",
+    "graphql"
+  ],
+  "author": "Hasna",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.0.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "restricted"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "src",
+    "README.md",
+    "CLAUDE.md"
+  ]
+}

package/connectors/connect-linear/src/api/client.ts

@@ -0,0 +1,62 @@
+import type { LinearConfig, GraphQLResponse } from '../types';
+import { LinearApiError } from '../types';
+
+const DEFAULT_BASE_URL = 'https://api.linear.app/graphql';
+
+export class LinearClient {
+  private readonly apiKey: string;
+  private readonly baseUrl: string;
+
+  constructor(config: LinearConfig) {
+    if (!config.apiKey) {
+      throw new Error('Linear API key is required');
+    }
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl || DEFAULT_BASE_URL;
+  }
+
+  /**
+   * Execute a GraphQL query
+   */
+  async query<T>(query: string, variables?: Record<string, unknown>): Promise<T> {
+    const response = await fetch(this.baseUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': this.apiKey,
+      },
+      body: JSON.stringify({ query, variables }),
+    });
+
+    if (!response.ok) {
+      throw new LinearApiError(
+        `HTTP ${response.status}: ${response.statusText}`,
+        'http_error',
+        response.status
+      );
+    }
+
+    const result = await response.json() as GraphQLResponse<T>;
+
+    if (result.errors && result.errors.length > 0) {
+      const error = result.errors[0];
+      throw new LinearApiError(
+        error.message,
+        error.extensions?.code as string || 'graphql_error'
+      );
+    }
+
+    if (!result.data) {
+      throw new LinearApiError('No data returned', 'no_data');
+    }
+
+    return result.data;
+  }
+
+  /**
+   * Execute a GraphQL mutation
+   */
+  async mutate<T>(mutation: string, variables?: Record<string, unknown>): Promise<T> {
+    return this.query<T>(mutation, variables);
+  }
+}

package/connectors/connect-linear/src/api/index.ts

@@ -0,0 +1,46 @@
+import type { LinearConfig } from '../types';
+import { LinearClient } from './client';
+import { IssuesApi } from './issues';
+import { ProjectsApi } from './projects';
+import { TeamsApi } from './teams';
+import { UsersApi } from './users';
+
+export { LinearClient } from './client';
+export { IssuesApi } from './issues';
+export { ProjectsApi } from './projects';
+export { TeamsApi } from './teams';
+export { UsersApi } from './users';
+
+/**
+ * Main Linear API class
+ */
+export class Linear {
+  private readonly client: LinearClient;
+
+  public readonly issues: IssuesApi;
+  public readonly projects: ProjectsApi;
+  public readonly teams: TeamsApi;
+  public readonly users: UsersApi;
+
+  constructor(config: LinearConfig) {
+    this.client = new LinearClient(config);
+    this.issues = new IssuesApi(this.client);
+    this.projects = new ProjectsApi(this.client);
+    this.teams = new TeamsApi(this.client);
+    this.users = new UsersApi(this.client);
+  }
+
+  /**
+   * Test authentication and return current user
+   */
+  async test() {
+    return this.users.me();
+  }
+
+  /**
+   * Get the GraphQL client for custom queries
+   */
+  getClient(): LinearClient {
+    return this.client;
+  }
+}