Conversation
Collaborator
Author
|
Feedback from meeting with @czottmann :
|
iamfj
commented
Feb 24, 2026
Add biome for formatting and linting, lefthook for git hooks, commitlint for conventional commit enforcement, and editorconfig for IDE consistency. Set up GraphQL Code Generator to produce TypeScript types from .graphql definition files. Migrate all queries and mutations from inline TypeScript strings to dedicated .graphql files under graphql/queries and graphql/mutations. Update CI workflow for the new tooling and add codegen, format, and lint scripts to package.json. Configure prebuild and postinstall hooks to ensure generated types stay in sync. Part of #45
Replace the flat utils-based structure with a strict five-layer architecture enforcing separation of concerns: CLI Input → Command → Resolver → Service → JSON Output Clients: - GraphQLClient: typed wrapper for raw GraphQL operations - LinearSdkClient: wrapper for Linear SDK access Common modules: - context: CommandContext factory with createContext() - errors: structured error helpers (notFoundError, etc.) - identifier: UUID detection and identifier parsing - output: typed outputSuccess/outputError functions - types: shared type aliases derived from codegen types - usage: DomainMeta system for self-documenting commands Resolvers (human ID → UUID, using LinearSdkClient): - team, project, label, status, issue, cycle, milestone, user Services (business logic, using GraphQLClient): - issue, document, attachment, file, comment, cycle, milestone, project, team, user, label, issue-relation, auth Commands rewritten to delegate through layers: - Rename embeds → files, project-milestones → milestones - Merge search into list commands - Add issue relation flags (--blocks, --blocked-by, --relates-to) - Add cursor pagination (--after, --limit) to all list commands - Add --assignee resolution by name or email - Add encrypted token auth (login, status, logout) - Add usage subcommand to every command group Remove old utils/, queries/ directories and their tests. Add comprehensive unit tests for all resolvers and services. Closes #27, closes #43, closes #47 Refs #2, #3, #14, #16 Part of #45, incorporates #50, #53
Rewrite all documentation to reflect the new five-layer architecture, updated CLI surface, and current development workflows. - AGENTS.md: restructure for machine-first readability with decision trees, anti-patterns, and layer invariants - README.md: rewrite for current CLI commands and agent optimization - docs/architecture.md: document five-layer component organization - docs/development.md: add service/resolver/command templates - docs/testing.md: add mock patterns per layer - docs/build-system.md: document codegen pipeline - docs/files.md: update file catalog for new structure Remove obsolete files: - docs/Linear-API@current.graphql (26k-line schema dump) - docs/plans/ (completed implementation plans) Part of #45 Refs #54
File download and upload commands returned exit code 0 with a JSON success envelope on failure. This caused LLM agents and scripts checking $? to misinterpret failed operations as successful. Failures now throw through handleCommand() like all other commands, producing JSON error output on stderr with exit code 1.
GraphQL requests and file operations had no timeout, causing the CLI to hang indefinitely on stalled connections. - GraphQL API requests: 30 second timeout (Promise.race) - File download/upload: 60 second timeout (AbortSignal.timeout) Especially important for LLM agents that have their own tool timeouts and need the CLI to fail fast with a clear error.
- SECURITY.md with responsible disclosure process and scope - GitHub issue templates (bug report form, feature request form) - PR template with verification checklist - Add contributors field to package.json
This was referenced Apr 7, 2026
Closed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Overview
214 files changed | +23,877 | -38,394 (net reduction of ~14.5k lines)
This release is a comprehensive overhaul: new architecture, new features, new tooling, and streamlined developer experience. Every layer of the codebase has been touched.
Changes by Category
Architecture — Five-Layer Redesign
The entire source tree was reorganized from a flat
utils/directory into a strict five-layer architecture with enforced separation of concerns:src/client/src/resolvers/LinearSdkClientsrc/services/GraphQLClientsrc/commands/createContext()src/common/Key rules enforced: ID resolution happens exactly once in resolvers; services accept only UUIDs; commands are thin orchestrators.
GraphQL Codegen Migration
Replaced all manually maintained TypeScript type definitions and runtime GraphQL string loading with
graphql-codegen. Everyclient.request<T>()call is now fully typed from codegen output..graphqlfilesFeatures
Authentication System
Full
linearis authcommand group with interactive login, encrypted AES-256-GCM token storage, token validation viaGetViewerquery, and structured auth error detection. Backwards-compatible with env var and legacy plaintext file.Issue Relations
New
issue-relation-servicewith create/find/delete operations. Relation flags (--blocks,--blocked-by,--related,--duplicate) on bothissues createandissues update.Cursor-Based Pagination
All list commands now support cursor-based pagination via
--after <cursor>and--limit <n>. Service layer returnsPaginatedResult<T>withpageInfocontainingendCursorandhasNextPage. Includes per-service tests for pagination behavior.Assignee ID Resolution
--assigneenow accepts human-readable names and emails in addition to UUIDs. NewresolveUserIdresolver handles the lookup.Two-Tier Usage System
Token-optimized usage output designed for LLM agents. Tier 1 overview (~200 tokens) and Tier 2 domain detail (~300-500 tokens).
USAGE.mdauto-generated on every build.src/queriesruntime loadersReliability
Request Timeouts
GraphQL API requests now have a 30-second timeout, file download/upload operations have a 60-second timeout. Prevents the CLI from hanging indefinitely on stalled connections — especially important for LLM agent integrations with their own tool timeouts.
File Operation Error Codes
files downloadandfiles uploadnow use proper error exit codes (exit 1) on failure instead of returning exit 0 with a JSONsuccess: falseenvelope. Consistent with all other commands.Developer Tooling
Documentation & Community
SECURITY.mdwith responsible disclosure process and scope definitionCONTRIBUTING.mdupdated with codegen network requirement noteUpstream Issues Addressed
--assigneefails with name instead of UUID → resolved by fix(commands): resolve --assignee to UUID in issues create/update #50Open Issues (deferred to next minor release)
These are tracked and labeled
next-release:getRootOpts()helper to replace fragile parent chain navigationPreviously tracked:
$projectIdof required typeString!was not provided #46 —milestones createfails with$projectIdnot provideddocs/plans/*.mdfiles before merge #51 — Add guard job to rejectdocs/plans/*.mdbefore mergeBreaking Changes
project-milestones→milestones,embeds→files--issues-first→--limit)searchsubcommands merged intolistwith filter flagssrc/(relevant for contributors)files downloadandfiles uploadnow exit with code 1 on failure (previously exit 0 withsuccess: falsein JSON body)All Included PRs (chronological)
Direct commits on
next(not via PR):fix: use proper error exit codes for file operation failuresfeat: add request timeouts for API and file operationsdocs: add security policy, community templates, and contributor metadataMerge Checklist