Merge upstream release/2025.11.2 and resolve conflicts

- Keep both our fragments (cycles, milestones) and upstream fragments (comments, parent, children)
- Rebuild dist files after conflict resolution

Author: ryanrozich

AGENTS.md

@@ -4,14 +4,19 @@ This file provides guidance to LLM agents when working with code in this reposit
 
 ## Project Overview
 
-This is a CLI tool for Linear.app that outputs structured JSON data, designed for LLM agents and users who prefer structured output. Written in Typescript, built with Node.js using Commander.js for CLI structure and the Linear GraphQL API.
+Linearis is a CLI tool for Linear.app that outputs structured JSON data, designed for LLM agents and users who prefer structured output. Written in TypeScript, built with Node.js using Commander.js for CLI structure and optimized GraphQL queries for Linear API integration.
+
+**Design philosophy:** Minimize token usage for LLM agents while providing rich, structured data. The entire usage guide (`linearis usage`) comes in under 1000 tokens.
 
 ## Key Commands
 
 ### Development Commands
 
-- `node src/main.ts` - Run the CLI application
-- `pnpm test` - Run tests (currently not implemented)
+- `pnpm start` - Run CLI in development mode using tsx (no compilation)
+- `pnpm run build` - Compile TypeScript to dist/ and make executable
+- `pnpm run clean` - Remove dist/ directory
+- `node dist/main.js` - Run compiled production version
+- `pnpm test` - Tests (currently not implemented)
 
 ### Package Management
 
@@ -23,53 +28,64 @@ This is a CLI tool for Linear.app that outputs structured JSON data, designed fo
 
 ### Core Components
 
-- **src/main.ts** - Main entry point and CLI command structure using Commander.js
-- **src/utils/linear-client.ts** - Complete Linear API service layer with smart ID resolution
-- **src/utils/auth.ts** - Authentication handling for API tokens
-- **src/utils/output.ts** - JSON output utilities and error handling
-- **src/commands/issues.ts** - Issues command implementation with full SPEC compliance
-- **src/commands/projects.ts** - Projects command implementation
-- **src/commands/embeds.ts** - File download command for Linear uploaded files
-- **src/utils/embed-parser.ts** - Markdown parsing for Linear upload URL extraction
-- **src/utils/file-service.ts** - Authenticated file download service with signed URL support
-- **package.json** - Node.js project configuration with pnpm package manager
+**Command Layer** (`src/commands/`)
+
+- Each command file exports a `setup*Commands(program)` function
+- Commands registered in `src/main.ts` with Commander.js
+- All commands use `handleAsyncCommand()` wrapper for consistent error handling
+- Current commands: issues, comments, labels, projects, cycles, projectMilestones
+
+**Service Layer** (`src/utils/`)
+
+- `graphql-service.ts` - Raw GraphQL execution and batch operations
+- `graphql-issues-service.ts` - Optimized single-query issue operations
+- `linear-service.ts` - Smart ID resolution and SDK fallback operations
+- `auth.ts` - Multi-source authentication (flag, env var, file)
+- `output.ts` - JSON formatting and error handling
+
+**Query Definitions** (`src/queries/`)
+
+- GraphQL query strings using fragments for reusability
+- `common.ts` contains shared fragments (COMPLETE_ISSUE_FRAGMENT, etc.)
+- Query files organized by entity (issues.ts, cycles.ts, projectMilestones.ts)
+
+**Type System** (`src/utils/linear-types.d.ts`)
+
+- TypeScript interfaces for all Linear entities
+- Ensures type safety across service layers
 
 ### Authentication Flow
 
-The CLI supports three authentication methods (in order of preference):
+Three authentication methods (checked in order):
 
 1. `--api-token` command flag
 2. `LINEAR_API_TOKEN` environment variable
 3. Plain text file at `$HOME/.linear_api_token`
 
-### Dependencies
+### Smart ID Resolution
 
-- **@linear/sdk** (^58.1.0) - Official Linear TypeScript SDK
-- **commander** (^14.0.0) - CLI framework for command structure
-- **tsx** (^4.20.5) - TypeScript execution for Node.js
+Users can provide human-friendly identifiers that get automatically resolved:
 
-### Technical Requirements
+- **Issue IDs**: `ABC-123` → UUID (parses team key + issue number)
+- **Project names**: `"Mobile App"` → project UUID
+- **Label names**: `"Bug", "Enhancement"` → label UUIDs
+- **Team identifiers**: `"ABC"` (key) or `"My Team"` (name) → team UUID
+- **Cycle names**: `"Sprint 2025-10"` → cycle UUID (with team disambiguation)
 
-- Node.js >= 22.0.0
-- Uses ES modules (implied by .ts and modern Node version)
-- All CLI output should be JSON format (except usage examples)
+All resolution happens in `LinearService` via `resolve*Id()` methods.
 
-### Development Notes
+### GraphQL Optimization Pattern
 
-- All TypeScript files are fully implemented with proper typing
-- LinearService provides smart ID resolution (ABC-123 → UUID, label names → IDs, etc.)
-- Issue creation supports both `--project` and `--project-id` flags as specified
-- Smart parameter conversion allows using human-friendly names instead of UUIDs
-- No testing framework currently configured
+**Problem:** Linear SDK creates N+1 queries when fetching related entities.
 
-### Smart ID Resolution Features
+**Solution:** Custom GraphQL queries with fragments fetch everything in one request.
 
-The CLI automatically handles conversions between user-friendly and internal identifiers:
+Example - listing issues:
 
-- **Issue IDs**: `ABC-123` ↔ internal UUID
-- **Project names**: `"My Project"` → project UUID
-- **Label names**: `"Bug", "Enhancement"` → label UUIDs
-- **Team keys/names**: `"ABC"` or `"My Team"` → team UUID
+- SDK approach: 1 query for issues + 5 queries per issue (team, assignee, state, project, labels) = 1 + (5 × N) queries
+- GraphQL approach: 1 query with all relationships embedded = 1 query total
+
+See `src/queries/common.ts` for fragment definitions and `src/utils/graphql-issues-service.ts` for usage.
 
 ### File Download Features
 
@@ -80,3 +96,51 @@ The CLI can extract and download files uploaded to Linear's private cloud storag
 - **File Downloads**: `embeds download <url>` command downloads files from signed URLs
 - **Expiration Tracking**: Each embed includes `expiresAt` timestamp (ISO 8601) indicating when the signed URL expires
 - **Smart Auth**: FileService automatically detects signed URLs and skips Bearer token authentication when signature is present
+
+## Development Patterns
+
+### Adding a New Command
+
+1. Create command file in `src/commands/` (e.g., `milestones.ts`)
+2. Export `setup*Commands(program: Command)` function
+3. Register in `src/main.ts` by importing and calling setup function
+4. Use `handleAsyncCommand()` wrapper for all async actions
+5. Create services with `createGraphQLService()` and/or `createLinearService()`
+6. Output results with `outputSuccess(data)` or let errors propagate
+
+### Adding GraphQL Queries
+
+1. Define fragments in `src/queries/common.ts` if reusable
+2. Create query strings in `src/queries/<entity>.ts`
+3. Use fragments to ensure consistent data fetching
+4. Add corresponding method in `GraphQLIssuesService` or create new service
+5. Test that all nested relationships are fetched in single query
+
+### Error Handling
+
+- All commands wrapped with `handleAsyncCommand()` which catches and formats errors
+- Service methods throw descriptive errors: `throw new Error("Team 'ABC' not found")`
+- GraphQL errors transformed to match service error patterns in `GraphQLService.rawRequest()`
+
+## Technical Requirements
+
+- Node.js >= 22.0.0
+- ES modules (type: "module" in package.json)
+- All CLI output must be JSON format (except help/usage text)
+- TypeScript with full type safety
+
+## Dependencies
+
+- `@linear/sdk` (^58.1.0) - Official Linear TypeScript SDK and GraphQL client
+- `commander` (^14.0.0) - CLI framework
+- `tsx` (^4.20.5) - TypeScript execution for development
+
+## Documentation
+
+Comprehensive docs in `docs/`:
+
+- `architecture.md` - Component organization, data flow, optimization patterns
+- `development.md` - Code patterns, TypeScript standards, common workflows
+- `build-system.md` - TypeScript compilation, automated builds
+- `testing.md` - Testing approach, manual validation, performance benchmarks
+- `files.md` - Complete file catalog

CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [2025.11.2] - TODO-TO-DO
+
+### Added
+
+- `issues` commands now include parent and child issue relationships
+  - `parent` field with `{ id, identifier, title }` for parent issue (if exists)
+  - `children` array with `{ id, identifier, title }` for immediate child issues
+  - Available in all issue commands: `read`, `list`, and `search`
+
+### Changed
+
+- Under-the-hood stability bug fixes.
+
 ## [2025.11.1] - 2025-11-06
 
 ### Added
@@ -41,6 +54,7 @@ All notable changes to this project will be documented in this file. The format
 
 - Initial release of Linearis CLI tool
 
+[2025.11.1]: https://github.com/czottmann/linearis/compare/2025.11.1...2025.11.2
 [2025.11.1]: https://github.com/czottmann/linearis/compare/1.1.0...2025.11.1
 [1.1.0]: https://github.com/czottmann/linearis/compare/1.0.0...1.1.0
 [1.0.0]: https://github.com/czottmann/linearis/releases/tag/1.0.0

dist/main.js

@@ -11,7 +11,7 @@ import { outputUsageInfo } from "./utils/usage.js";
 program
     .name("linearis")
     .description("CLI for Linear.app with JSON output")
-    .version("2025.11.1")
+    .version("2025.11.2")
     .option("--api-token <token>", "Linear API token");
 program.action(() => {
     program.help();

dist/queries/common.js

@@ -69,6 +69,22 @@ export const ISSUE_COMMENTS_FRAGMENT = `
     }
   }
 `;
+export const ISSUE_PARENT_FRAGMENT = `
+  parent {
+    id
+    identifier
+    title
+  }
+`;
+export const ISSUE_CHILDREN_FRAGMENT = `
+  children {
+    nodes {
+      id
+      identifier
+      title
+    }
+  }
+`;
 export const COMPLETE_ISSUE_FRAGMENT = `
   ${ISSUE_CORE_FIELDS}
   ${ISSUE_STATE_FRAGMENT}
@@ -78,6 +94,8 @@ export const COMPLETE_ISSUE_FRAGMENT = `
   ${ISSUE_LABELS_FRAGMENT}
   ${ISSUE_CYCLE_FRAGMENT}
   ${ISSUE_PROJECT_MILESTONE_FRAGMENT}
+  ${ISSUE_PARENT_FRAGMENT}
+  ${ISSUE_CHILDREN_FRAGMENT}
 `;
 export const COMPLETE_ISSUE_WITH_COMMENTS_FRAGMENT = `
   ${COMPLETE_ISSUE_FRAGMENT}

dist/queries/issues.js

@@ -157,7 +157,7 @@ export const BATCH_RESOLVE_FOR_UPDATE_QUERY = `
       }
     }
 
-    # Resolve issue by identifier if needed
+    # Resolve issue identifier if provided
     issues(
       filter: {
         and: [

dist/utils/graphql-issues-service.js

@@ -1,6 +1,7 @@
 import { BATCH_RESOLVE_FOR_CREATE_QUERY, BATCH_RESOLVE_FOR_SEARCH_QUERY, BATCH_RESOLVE_FOR_UPDATE_QUERY, CREATE_ISSUE_MUTATION, FILTERED_SEARCH_ISSUES_QUERY, GET_ISSUE_BY_ID_QUERY, GET_ISSUE_BY_IDENTIFIER_QUERY, GET_ISSUES_QUERY, SEARCH_ISSUES_QUERY, UPDATE_ISSUE_MUTATION, } from "../queries/issues.js";
 import { extractEmbeds } from "./embed-parser.js";
 import { isUuid } from "./uuid.js";
+import { parseIssueIdentifier, tryParseIssueIdentifier, } from "./identifier-parser.js";
 export class GraphQLIssuesService {
     graphQLService;
     linearService;
@@ -30,15 +31,7 @@ export class GraphQLIssuesService {
             issueData = result.issue;
         }
         else {
-            const parts = issueId.split("-");
-            if (parts.length !== 2) {
-                throw new Error(`Invalid issue identifier format: "${issueId}". Expected format: TEAM-123`);
-            }
-            const teamKey = parts[0];
-            const issueNumber = parseInt(parts[1]);
-            if (isNaN(issueNumber)) {
-                throw new Error(`Invalid issue number in identifier: "${issueId}"`);
-            }
+            const { teamKey, issueNumber } = parseIssueIdentifier(issueId);
             const result = await this.graphQLService.rawRequest(GET_ISSUE_BY_IDENTIFIER_QUERY, {
                 teamKey,
                 number: issueNumber,
@@ -55,15 +48,9 @@ export class GraphQLIssuesService {
         let currentIssueLabels = [];
         const resolveVariables = {};
         if (!isUuid(args.id)) {
-            const parts = args.id.split("-");
-            if (parts.length !== 2) {
-                throw new Error(`Invalid issue identifier format: "${args.id}". Expected format: TEAM-123`);
-            }
-            resolveVariables.teamKey = parts[0];
-            resolveVariables.issueNumber = parseInt(parts[1]);
-            if (isNaN(resolveVariables.issueNumber)) {
-                throw new Error(`Invalid issue number in identifier: "${args.id}"`);
-            }
+            const { teamKey, issueNumber } = parseIssueIdentifier(args.id);
+            resolveVariables.teamKey = teamKey;
+            resolveVariables.issueNumber = issueNumber;
         }
         if (args.labelIds && Array.isArray(args.labelIds)) {
             const labelNames = args.labelIds.filter((id) => !isUuid(id));
@@ -250,14 +237,10 @@ export class GraphQLIssuesService {
             }
         }
         if (args.parentId && !isUuid(args.parentId)) {
-            const parts = args.parentId.split("-");
-            if (parts.length === 2) {
-                const teamKey = parts[0];
-                const issueNumber = parseInt(parts[1]);
-                if (!isNaN(issueNumber)) {
-                    resolveVariables.parentTeamKey = teamKey;
-                    resolveVariables.parentIssueNumber = issueNumber;
-                }
+            const parentParsed = tryParseIssueIdentifier(args.parentId);
+            if (parentParsed) {
+                resolveVariables.parentTeamKey = parentParsed.teamKey;
+                resolveVariables.parentIssueNumber = parentParsed.issueNumber;
             }
         }
         let resolveResult = {};
@@ -520,6 +503,18 @@ export class GraphQLIssuesService {
                 id: label.id,
                 name: label.name,
             })),
+            parent: issue.parent
+                ? {
+                    id: issue.parent.id,
+                    identifier: issue.parent.identifier,
+                    title: issue.parent.title,
+                }
+                : undefined,
+            children: issue.children?.nodes.map((child) => ({
+                id: child.id,
+                identifier: child.identifier,
+                title: child.title,
+            })) || undefined,
             comments: issue.comments?.nodes.map((comment) => ({
                 id: comment.id,
                 body: comment.body,

dist/utils/identifier-parser.js

@@ -0,0 +1,20 @@
+export function parseIssueIdentifier(identifier) {
+    const parts = identifier.split("-");
+    if (parts.length !== 2) {
+        throw new Error(`Invalid issue identifier format: "${identifier}". Expected format: TEAM-123`);
+    }
+    const teamKey = parts[0];
+    const issueNumber = parseInt(parts[1]);
+    if (isNaN(issueNumber)) {
+        throw new Error(`Invalid issue number in identifier: "${identifier}"`);
+    }
+    return { teamKey, issueNumber };
+}
+export function tryParseIssueIdentifier(identifier) {
+    try {
+        return parseIssueIdentifier(identifier);
+    }
+    catch {
+        return null;
+    }
+}

dist/utils/linear-service.js

@@ -1,6 +1,7 @@
 import { LinearClient } from "@linear/sdk";
 import { getApiToken } from "./auth.js";
 import { isUuid } from "./uuid.js";
+import { parseIssueIdentifier } from "./identifier-parser.js";
 const DEFAULT_CYCLE_PAGINATION_LIMIT = 250;
 function resolveId(input) {
     if (isUuid(input)) {
@@ -29,15 +30,7 @@ export class LinearService {
         if (isUuid(issueId)) {
             return issueId;
         }
-        const parts = issueId.split("-");
-        if (parts.length !== 2) {
-            throw new Error(`Invalid issue identifier format: "${issueId}". Expected format: TEAM-123`);
-        }
-        const teamKey = parts[0];
-        const issueNumber = parseInt(parts[1]);
-        if (isNaN(issueNumber)) {
-            throw new Error(`Invalid issue number in identifier: "${issueId}"`);
-        }
+        const { teamKey, issueNumber } = parseIssueIdentifier(issueId);
         const issues = await this.client.issues({
             filter: {
                 number: { eq: issueNumber },

package.json

@@ -1,6 +1,6 @@
 {
   "name": "linearis",
-  "version": "2025.11.1",
+  "version": "2025.11.2",
   "description": "CLI tool for Linear.app with JSON output, smart ID resolution, and optimized GraphQL queries. Designed for LLM agents and humans who prefer structured data.",
   "main": "dist/main.js",
   "type": "module",