@lsctech/polaris 0.1.0

package/dist/tracker/adapters/linear/index.js

@@ -0,0 +1,621 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LinearAdapter = void 0;
+const local_graph_js_1 = require("../../local-graph.js");
+const schema_js_1 = require("../../schema.js");
+const node_https_1 = require("node:https");
+class LinearGraphqlClient {
+    apiKey;
+    constructor(apiKey) {
+        this.apiKey = apiKey;
+    }
+    async graphql(query, variables) {
+        if (!this.apiKey) {
+            throw new Error("LINEAR_API_KEY is required for the 'linear' tracker adapter.");
+        }
+        const payload = JSON.stringify({ query, variables });
+        const raw = await new Promise((resolve, reject) => {
+            const req = (0, node_https_1.request)({
+                hostname: "api.linear.app",
+                path: "/graphql",
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: this.apiKey,
+                },
+            }, (res) => {
+                const chunks = [];
+                res.on("data", (chunk) => chunks.push(chunk));
+                res.on("end", () => {
+                    const responseBody = Buffer.concat(chunks).toString("utf-8");
+                    if ((res.statusCode ?? 0) >= 400) {
+                        reject(new Error(`Linear API returned ${res.statusCode}: ${responseBody || "<empty response body>"}`));
+                        return;
+                    }
+                    resolve(responseBody);
+                });
+            });
+            req.on("error", reject);
+            req.write(payload);
+            req.end();
+        });
+        const parsed = JSON.parse(raw);
+        if (parsed.errors && parsed.errors.length > 0) {
+            throw new Error(`Linear API GraphQL errors: ${JSON.stringify(parsed.errors)}`);
+        }
+        if (!parsed.data) {
+            throw new Error("Linear API returned no data.");
+        }
+        return parsed.data;
+    }
+    async listTeams() {
+        const data = await this.graphql("query PolarisLinearTeams { teams(first: 250) { nodes { id name } } }", {});
+        return data.teams.nodes;
+    }
+    async listProjects(teamId) {
+        const data = await this.graphql(`
+        query PolarisLinearProjects($teamId: String!) {
+          projects(filter: { teams: { some: { id: { eq: $teamId } } } }, first: 250) {
+            nodes { id name }
+          }
+        }
+      `, { teamId });
+        return data.projects.nodes;
+    }
+    async listIssues(filters) {
+        const data = await this.graphql(`
+        query PolarisLinearIssues($teamId: String, $projectId: String) {
+          issues(
+            first: 250
+            filter: {
+              team: { id: { eq: $teamId } }
+              project: { id: { eq: $projectId } }
+            }
+          ) {
+            nodes {
+              id
+              identifier
+              title
+              description
+              state { id name }
+              children {
+                nodes {
+                  id
+                  identifier
+                  title
+                  description
+                  state { id name }
+                }
+              }
+              relations {
+                nodes {
+                  id
+                  type
+                  issue {
+                    id
+                    identifier
+                    title
+                    state { id name }
+                  }
+                  relatedIssue {
+                    id
+                    identifier
+                    title
+                    state { id name }
+                  }
+                }
+              }
+              inverseRelations {
+                nodes {
+                  id
+                  type
+                  issue {
+                    id
+                    identifier
+                    title
+                    state { id name }
+                  }
+                  relatedIssue {
+                    id
+                    identifier
+                    title
+                    state { id name }
+                  }
+                }
+              }
+            }
+          }
+        }
+      `, {
+            teamId: filters.teamId ?? null,
+            projectId: filters.projectId ?? null,
+        });
+        return data.issues.nodes;
+    }
+    async getIssueById(id) {
+        const data = await this.graphql(`
+        query PolarisLinearIssueById($id: String!) {
+          issue(id: $id) {
+            id
+            identifier
+            title
+            description
+            state { id name }
+            children {
+              nodes {
+                id
+                identifier
+                title
+                state { id name }
+              }
+            }
+            relations {
+              nodes {
+              id
+              type
+              issue {
+                id
+                identifier
+                title
+                state { id name }
+              }
+              relatedIssue {
+                id
+                identifier
+                title
+                state { id name }
+              }
+              }
+            }
+            inverseRelations {
+              nodes {
+              id
+              type
+              issue {
+                id
+                identifier
+                title
+                state { id name }
+              }
+              relatedIssue {
+                id
+                identifier
+                title
+                state { id name }
+              }
+              }
+            }
+          }
+        }
+      `, { id });
+        return data.issue;
+    }
+}
+/**
+ * Implements the Linear direct adapter for synchronizing issues.
+ */
+class LinearAdapter {
+    config;
+    linearClient;
+    constructor(config, linearClient) {
+        this.config = config;
+        this.linearClient = linearClient ?? new LinearGraphqlClient(process.env["LINEAR_API_KEY"]);
+    }
+    issueNodeId(issue) {
+        return issue.identifier ?? issue.id;
+    }
+    addDependencyToMap(dependencies, nodeId, dependsOnNodeId) {
+        if (!dependencies[nodeId]) {
+            dependencies[nodeId] = [];
+        }
+        if (!dependencies[nodeId].includes(dependsOnNodeId)) {
+            dependencies[nodeId].push(dependsOnNodeId);
+        }
+    }
+    upsertNode(nodes, issue) {
+        const nodeId = this.issueNodeId(issue);
+        const statusName = issue.state?.name ?? issue.state?.id ?? "Unknown";
+        if (!nodes[nodeId]) {
+            nodes[nodeId] = {
+                id: nodeId,
+                title: issue.title ?? issue.identifier ?? issue.id,
+                status: statusName,
+                ...(issue.description ? { body: issue.description } : {}),
+            };
+            return nodeId;
+        }
+        if (issue.title &&
+            (!nodes[nodeId].title ||
+                nodes[nodeId].title === issue.identifier ||
+                nodes[nodeId].title === issue.id)) {
+            nodes[nodeId].title = issue.title;
+        }
+        if ((nodes[nodeId].status === "Unknown" || !nodes[nodeId].status) && issue.state) {
+            nodes[nodeId].status = statusName;
+        }
+        if (issue.description && !nodes[nodeId].body) {
+            nodes[nodeId].body = issue.description;
+        }
+        return nodeId;
+    }
+    relationDependency(relation, issueNodeId) {
+        if (!relation.issue || !relation.relatedIssue || !relation.type) {
+            return null;
+        }
+        const relationType = this.normalizeRelationType(relation.type);
+        const sourceNodeId = this.issueNodeId(relation.issue);
+        const relatedNodeId = this.issueNodeId(relation.relatedIssue);
+        if (sourceNodeId !== issueNodeId && relatedNodeId !== issueNodeId) {
+            return null;
+        }
+        if (relationType === "BLOCKS") {
+            return {
+                fromId: relatedNodeId,
+                dependsOnId: sourceNodeId,
+            };
+        }
+        if (relationType === "BLOCKED_BY" || relationType === "DEPENDS_ON") {
+            return {
+                fromId: sourceNodeId,
+                dependsOnId: relatedNodeId,
+            };
+        }
+        console.warn(`Linear relation type '${relation.type}' is not mapped to dependencies (supported types: blocks, blocked_by, depends_on); ignoring.`);
+        return null;
+    }
+    normalizeRelationType(type) {
+        return type.trim().toUpperCase().replace(/[^A-Z0-9]+/g, "_");
+    }
+    mapIssueRelations(issue, nodes, dependencies) {
+        const issueNodeId = this.upsertNode(nodes, issue);
+        const relationNodes = [
+            ...(issue.relations?.nodes ?? []),
+            ...(issue.inverseRelations?.nodes ?? []),
+        ];
+        for (const relation of relationNodes) {
+            if (relation.issue) {
+                this.upsertNode(nodes, relation.issue);
+            }
+            if (relation.relatedIssue) {
+                this.upsertNode(nodes, relation.relatedIssue);
+            }
+            const dependency = this.relationDependency(relation, issueNodeId);
+            if (!dependency) {
+                continue;
+            }
+            this.addDependencyToMap(dependencies, dependency.fromId, dependency.dependsOnId);
+        }
+        for (const childIssue of issue.children?.nodes ?? []) {
+            this.upsertNode(nodes, childIssue);
+        }
+    }
+    async collectIssueAndChildren(issueId) {
+        const rootIssue = await this.linearClient.getIssueById(issueId);
+        if (!rootIssue) {
+            throw new Error(`Linear issue ID '${issueId}' not found.`);
+        }
+        const issueMap = new Map([[rootIssue.id, rootIssue]]);
+        const pendingChildIds = (rootIssue.children?.nodes ?? []).map((child) => child.id);
+        const fetchedChildIds = new Set();
+        let queueIndex = 0;
+        while (queueIndex < pendingChildIds.length) {
+            const childId = pendingChildIds[queueIndex];
+            queueIndex += 1;
+            if (!childId || fetchedChildIds.has(childId)) {
+                continue;
+            }
+            fetchedChildIds.add(childId);
+            const childIssue = await this.linearClient.getIssueById(childId);
+            if (!childIssue) {
+                continue;
+            }
+            issueMap.set(childIssue.id, childIssue);
+            for (const grandchild of childIssue.children?.nodes ?? []) {
+                if (!fetchedChildIds.has(grandchild.id)) {
+                    pendingChildIds.push(grandchild.id);
+                }
+            }
+        }
+        return Array.from(issueMap.values());
+    }
+    /**
+     * Synchronizes issues from Linear into a LocalGraph format.
+     * @returns A promise that resolves to a LocalGraph instance.
+     */
+    async syncIn(issueIdentifier) {
+        const linearConfig = this.config.tracker?.linear;
+        if (!linearConfig || !linearConfig.enabled) {
+            throw new Error("Linear tracker not enabled in config.");
+        }
+        const teamId = linearConfig.teamId;
+        const projectId = linearConfig.projectId;
+        let issues = [];
+        let teamName;
+        let resolvedTeamId;
+        let sourceId;
+        let sourceDoc;
+        let activeClusterId;
+        let clusterTitle;
+        if (issueIdentifier) {
+            issues = await this.collectIssueAndChildren(issueIdentifier);
+            sourceId = issueIdentifier;
+            sourceDoc = `Synchronized from Linear issue identifier: ${issueIdentifier}`;
+            activeClusterId = issueIdentifier;
+            clusterTitle = `Linear Issue: ${issueIdentifier}`;
+        }
+        else if (teamId) {
+            const teamsResponse = await this.linearClient.listTeams();
+            const team = teamsResponse.find(t => t.id === teamId || t.name === teamId);
+            if (!team) {
+                throw new Error(`Linear team with ID or name '${teamId}' not found.`);
+            }
+            teamName = team.name;
+            resolvedTeamId = team.id;
+            const listIssuesArgs = { teamId: team.id };
+            if (projectId) {
+                const projectsResponse = await this.linearClient.listProjects(team.id);
+                const project = projectsResponse.find(p => p.id === projectId || p.name === projectId);
+                if (!project) {
+                    throw new Error(`Linear project with ID or name '${projectId}' not found in team '${team.name}'.`);
+                }
+                listIssuesArgs.projectId = project.id;
+            }
+            issues = await this.linearClient.listIssues(listIssuesArgs);
+            sourceId = resolvedTeamId ?? teamId;
+            sourceDoc = `Synchronized from Linear team: ${teamName}${projectId ? `, project: ${projectId}` : ''}`;
+            if (projectId && teamName) {
+                activeClusterId = `${teamName}-${projectId}`;
+                clusterTitle = `Linear Project: ${projectId} (${teamName})`;
+            }
+            else {
+                activeClusterId = teamName;
+                clusterTitle = `Linear Team: ${teamName}`;
+            }
+        }
+        else {
+            console.warn("No Linear teamId specified in config. Fetching all accessible Linear issues. Consider specifying 'teamId' for better scope.");
+            issues = await this.linearClient.listIssues({});
+            sourceId = "all-linear-issues";
+            sourceDoc = "Synchronized from Linear team: all";
+            activeClusterId = "default";
+            clusterTitle = "All Linear Issues";
+        }
+        const nodes = {};
+        const dependencies = {};
+        const clusters = {};
+        clusters[activeClusterId] = {
+            id: activeClusterId,
+            title: clusterTitle,
+            children: [],
+        };
+        const clusterChildren = new Set();
+        // In single-target mode the first issue is the cluster root — a context node,
+        // not a dispatch target. Only its fetched descendants are runnable children.
+        // Relation-referenced issues go into the nodes map for graph reference but
+        // must not be promoted to runnable children.
+        const clusterRootNodeId = issueIdentifier && issues.length > 0 ? this.issueNodeId(issues[0]) : null;
+        for (const issue of issues) {
+            this.mapIssueRelations(issue, nodes, dependencies);
+            if (clusterRootNodeId !== null) {
+                // Single-target mode: every fetched descendant except the root is runnable.
+                const nodeId = this.issueNodeId(issue);
+                if (nodeId !== clusterRootNodeId) {
+                    clusterChildren.add(nodeId);
+                }
+                // Relation targets are added to nodes by mapIssueRelations above but
+                // are intentionally excluded from runnable children here.
+            }
+            else {
+                // Team/project mode: all fetched issues plus their relations are runnable.
+                clusterChildren.add(this.issueNodeId(issue));
+                for (const relation of issue.relations?.nodes ?? []) {
+                    if (relation.issue) {
+                        clusterChildren.add(this.issueNodeId(relation.issue));
+                    }
+                    if (relation.relatedIssue) {
+                        clusterChildren.add(this.issueNodeId(relation.relatedIssue));
+                    }
+                }
+                for (const relation of issue.inverseRelations?.nodes ?? []) {
+                    if (relation.issue) {
+                        clusterChildren.add(this.issueNodeId(relation.issue));
+                    }
+                    if (relation.relatedIssue) {
+                        clusterChildren.add(this.issueNodeId(relation.relatedIssue));
+                    }
+                }
+                for (const childIssue of issue.children?.nodes ?? []) {
+                    clusterChildren.add(this.issueNodeId(childIssue));
+                }
+            }
+        }
+        // Single-target leaf: root has no implementation children → root is itself runnable.
+        if (clusterRootNodeId !== null && clusterChildren.size === 0) {
+            clusterChildren.add(clusterRootNodeId);
+        }
+        clusters[activeClusterId] = {
+            ...clusters[activeClusterId],
+            children: Array.from(clusterChildren),
+            ...(clusterRootNodeId !== null ? { cluster_root: clusterRootNodeId } : {}),
+        };
+        const graph = {
+            schemaVersion: "v2",
+            source: {
+                id: sourceId,
+                type: "Linear",
+                analysis: {
+                    id: "initial-sync",
+                    doc: sourceDoc,
+                },
+            },
+            nodes: nodes,
+            dependencies: dependencies,
+            clusters: clusters,
+            activeCluster: activeClusterId,
+        };
+        const validatedGraph = schema_js_1.executionGraphV2Schema.parse(graph);
+        return local_graph_js_1.LocalGraph.fromGraph(validatedGraph);
+    }
+    /**
+     * Synchronizes local changes back to Linear.
+     * This includes status updates, comments, and link mutations.
+     */
+    async syncOut() {
+        console.log("LinearAdapter: syncOut not yet fully implemented.");
+        // TODO: Implement export/apply behavior for queued status/comment/link mutations.
+        // This will involve using mcp_linear_save_issue and mcp_linear_save_comment.
+    }
+    /**
+     * Returns the capabilities supported by the Linear adapter.
+     */
+    getCapabilities() {
+        return {
+            supportsChildRelationships: true,
+            supportsStatusUpdates: true,
+            supportsComments: true,
+            supportsLinks: true,
+            supportsDependencies: true,
+            supportsLifecycleMapping: true,
+            supportsCreateChild: true,
+        };
+    }
+    /**
+     * Maps a Linear state to a normalized lifecycle state.
+     *
+     * This mapping is heuristic and team-agnostic. It uses common patterns
+     * from Linear workflows but does not hardcode specific team state names.
+     * Teams with custom state names may need to configure explicit mappings.
+     *
+     * @param nativeStatus - The native Linear state name.
+     * @returns A status mapping result with the normalized state and support status.
+     */
+    mapNativeStatus(nativeStatus) {
+        const normalizedStatus = nativeStatus.toLowerCase().trim();
+        // Common backlog state patterns
+        if (["backlog", "todo", "idea", "suggestion", "unstarted"].includes(normalizedStatus)) {
+            return { lifecycleState: "backlog", supported: true };
+        }
+        // Common in-progress state patterns
+        if (["in progress", "in-progress", "started", "doing", "active", "wip"].includes(normalizedStatus)) {
+            return { lifecycleState: "in_progress", supported: true };
+        }
+        // Common in-review state patterns
+        if (["in review", "in-review", "review", "under review", "pending review", "ready for review"].includes(normalizedStatus)) {
+            return { lifecycleState: "in_review", supported: true };
+        }
+        // Common done state patterns
+        if (["done", "completed", "finished", "closed", "resolved", "shipped", "released"].includes(normalizedStatus)) {
+            return { lifecycleState: "done", supported: true };
+        }
+        // Common blocked state patterns
+        if (["blocked", "blocked by", "waiting", "on hold", "paused", "stuck"].includes(normalizedStatus)) {
+            return { lifecycleState: "blocked", supported: true };
+        }
+        // Common cancelled state patterns
+        if (["cancelled", "canceled", "declined", "won't do", "wont do", "duplicate", "invalid"].includes(normalizedStatus)) {
+            return { lifecycleState: "cancelled", supported: true };
+        }
+        // Unknown state - treat as unsupported but don't fail
+        return {
+            lifecycleState: "no_status_change",
+            supported: false,
+            reason: `Unknown Linear state '${nativeStatus}'. Consider adding explicit state mapping configuration.`,
+        };
+    }
+    /**
+     * Attempts to transition a Linear issue to a lifecycle state.
+     *
+     * @param taskId - The Linear issue ID or identifier.
+     * @param lifecycleState - The target normalized lifecycle state.
+     * @param evidence - Optional evidence for the transition (e.g., commit hash).
+     * @returns A lifecycle transition result indicating success, skip, or failure.
+     */
+    async transitionLifecycleState(taskId, lifecycleState, evidence) {
+        if (lifecycleState === "no_status_change") {
+            return {
+                applied: false,
+                skipped: true,
+                skipReason: "Lifecycle state is 'no_status_change', skipping transition",
+            };
+        }
+        // Linear requires team-specific state IDs for state transitions.
+        // This implementation is a placeholder - full implementation would need:
+        // 1. Fetch available states for the issue's team
+        // 2. Map normalized lifecycle state to a specific Linear state ID
+        // 3. Use GraphQL mutation to update the issue state
+        console.warn(`LinearAdapter: transitionLifecycleState not fully implemented. Would transition ${taskId} to ${lifecycleState}.`);
+        return {
+            applied: false,
+            skipped: true,
+            skipReason: "Lifecycle state transitions are not yet implemented for Linear adapter",
+        };
+    }
+    /**
+     * Adds a comment to a Linear issue.
+     *
+     * @param taskId - The Linear issue ID or identifier.
+     * @param body - The comment body text.
+     * @returns A comment result indicating success, skip, or failure.
+     */
+    async addComment(taskId, body) {
+        // Placeholder implementation - would use GraphQL mutation to create comment
+        console.warn(`LinearAdapter: addComment not fully implemented. Would add comment to ${taskId}.`);
+        return {
+            added: false,
+            unsupported: false,
+            error: "Adding comments is not yet implemented for Linear adapter",
+        };
+    }
+    /**
+     * Attaches a link to a Linear issue.
+     *
+     * @param taskId - The Linear issue ID or identifier.
+     * @param url - The URL to attach.
+     * @param title - Optional title for the link.
+     * @returns A link result indicating success, skip, or failure.
+     */
+    async attachLink(taskId, url, title) {
+        // Linear doesn't have a native "link" attachment concept.
+        // Links are typically added as comments or in the description.
+        console.warn(`LinearAdapter: attachLink not supported. Linear uses comments for links.`);
+        return {
+            attached: false,
+            unsupported: true,
+            reason: "Linear does not have native link attachments. Use addComment to include URLs.",
+        };
+    }
+    /**
+     * Adds a dependency relation between Linear issues.
+     *
+     * @param taskId - The ID of the issue that depends on another.
+     * @param dependsOnTaskId - The ID of the issue that is depended on.
+     * @returns A dependency result indicating success, skip, or failure.
+     */
+    async addDependency(taskId, dependsOnTaskId) {
+        // Placeholder implementation - would use GraphQL mutation to create relation
+        console.warn(`LinearAdapter: addDependency not fully implemented. Would add dependency from ${taskId} to ${dependsOnTaskId}.`);
+        return {
+            added: false,
+            unsupported: false,
+            error: "Adding dependencies is not yet implemented for Linear adapter",
+        };
+    }
+    /**
+     * Creates a child Linear issue under a parent issue.
+     *
+     * @param parentId - The ID of the parent issue.
+     * @param title - The title of the child issue.
+     * @param body - Optional body/description of the child issue.
+     * @returns A create child result indicating success, skip, or failure.
+     */
+    async createChild(parentId, title, body) {
+        // Placeholder implementation - would use GraphQL mutation to create issue with parent
+        console.warn(`LinearAdapter: createChild not fully implemented. Would create child '${title}' under ${parentId}.`);
+        return {
+            created: false,
+            unsupported: false,
+            error: "Creating child issues is not yet implemented for Linear adapter",
+        };
+    }
+}
+exports.LinearAdapter = LinearAdapter;