@lsctech/polaris 0.1.0

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

@@ -0,0 +1,238 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const index_js_1 = require("./index.js");
+const local_graph_js_1 = require("../../local-graph.js");
+(0, vitest_1.describe)("LinearAdapter", () => {
+    let config;
+    let linearClient;
+    (0, vitest_1.beforeEach)(() => {
+        config = {
+            tracker: {
+                linear: {
+                    enabled: true,
+                    teamId: "mock-team-id",
+                    projectId: "mock-project-id",
+                },
+            },
+        };
+        linearClient = {
+            listTeams: vitest_1.vi.fn(),
+            listProjects: vitest_1.vi.fn(),
+            listIssues: vitest_1.vi.fn(),
+            getIssueById: vitest_1.vi.fn(),
+        };
+        linearClient.listTeams.mockResolvedValue([
+            { id: "mock-team-id", name: "Mock Team" },
+        ]);
+        linearClient.listProjects.mockResolvedValue([
+            { id: "mock-project-id", name: "Mock Project" },
+        ]);
+        linearClient.listIssues.mockResolvedValue([
+            {
+                id: "issue-1",
+                title: "Test Issue 1",
+                state: { id: "status-id-1", name: "Todo" },
+                relations: {
+                    nodes: [
+                        {
+                            id: "rel-1",
+                            type: "blocks",
+                            issue: { id: "issue-2" },
+                            relatedIssue: { id: "issue-1" },
+                        },
+                    ],
+                },
+                inverseRelations: { nodes: [] },
+                children: { nodes: [] },
+            },
+            {
+                id: "issue-2",
+                title: "Test Issue 2",
+                state: { id: "status-id-2", name: "In Progress" },
+                relations: { nodes: [] },
+                inverseRelations: { nodes: [] },
+                children: { nodes: [] },
+            },
+        ]);
+        linearClient.getIssueById.mockResolvedValueOnce({
+            id: "root-issue-id",
+            identifier: "POL-198",
+            title: "Root issue",
+            state: { id: "status-id-3", name: "Todo" },
+            relations: {
+                nodes: [
+                    {
+                        id: "rel-2",
+                        type: "blocked_by",
+                        issue: { id: "root-issue-id", identifier: "POL-198", title: "Root issue" },
+                        relatedIssue: { id: "blocker-id", identifier: "POL-42", title: "Blocking issue" },
+                    },
+                    {
+                        id: "rel-3",
+                        type: "blocks",
+                        issue: { id: "root-issue-id", identifier: "POL-198", title: "Root issue" },
+                        relatedIssue: { id: "blocked-id", identifier: "POL-199", title: "Blocked issue" },
+                    },
+                ],
+            },
+            inverseRelations: { nodes: [] },
+            children: { nodes: [{ id: "child-issue-id", identifier: "POL-200", title: "Child issue" }] },
+        });
+        linearClient.getIssueById.mockResolvedValue({
+            id: "child-issue-id",
+            identifier: "POL-200",
+            title: "Child issue",
+            state: { id: "status-id-4", name: "In Progress" },
+            relations: { nodes: [] },
+            inverseRelations: { nodes: [] },
+            children: { nodes: [] },
+        });
+    });
+    (0, vitest_1.afterEach)(() => {
+        vitest_1.vi.clearAllMocks();
+    });
+    (0, vitest_1.it)("throws when LINEAR_API_KEY is missing for direct Linear API usage", async () => {
+        const originalApiKey = process.env["LINEAR_API_KEY"];
+        delete process.env["LINEAR_API_KEY"];
+        config.tracker.linear.teamId = "mock-team-id";
+        try {
+            const adapter = new index_js_1.LinearAdapter(config);
+            await (0, vitest_1.expect)(adapter.syncIn()).rejects.toThrow("LINEAR_API_KEY is required for the 'linear' tracker adapter.");
+        }
+        finally {
+            if (originalApiKey === undefined) {
+                delete process.env["LINEAR_API_KEY"];
+            }
+            else {
+                process.env["LINEAR_API_KEY"] = originalApiKey;
+            }
+        }
+    });
+    (0, vitest_1.it)("should return a LocalGraph instance", async () => {
+        const adapter = new index_js_1.LinearAdapter(config, linearClient);
+        const graph = await adapter.syncIn();
+        (0, vitest_1.expect)(graph).toBeInstanceOf(local_graph_js_1.LocalGraph);
+    });
+    (0, vitest_1.it)("should correctly map Linear issues to ExecutionGraphV2 nodes", async () => {
+        const adapter = new index_js_1.LinearAdapter(config, linearClient);
+        const graph = await adapter.syncIn();
+        const fullGraph = graph.fullGraph;
+        (0, vitest_1.expect)(fullGraph.nodes["issue-1"]).toEqual({
+            id: "issue-1",
+            title: "Test Issue 1",
+            status: "Todo",
+        });
+        (0, vitest_1.expect)(fullGraph.nodes["issue-2"]).toEqual({
+            id: "issue-2",
+            title: "Test Issue 2",
+            status: "In Progress",
+        });
+    });
+    (0, vitest_1.it)("should correctly map Linear issue dependencies", async () => {
+        const adapter = new index_js_1.LinearAdapter(config, linearClient);
+        const graph = await adapter.syncIn();
+        const fullGraph = graph.fullGraph;
+        (0, vitest_1.expect)(fullGraph.dependencies["issue-1"]).toEqual(["issue-2"]);
+        (0, vitest_1.expect)(fullGraph.dependencies["issue-2"]).toBeUndefined();
+    });
+    (0, vitest_1.it)("should create a cluster based on project and team IDs", async () => {
+        const adapter = new index_js_1.LinearAdapter(config, linearClient);
+        const graph = await adapter.syncIn();
+        const fullGraph = graph.fullGraph;
+        const expectedClusterId = "Mock Team-mock-project-id";
+        (0, vitest_1.expect)(fullGraph.activeCluster).toBe(expectedClusterId);
+        (0, vitest_1.expect)(fullGraph.clusters[expectedClusterId]).toEqual({
+            id: expectedClusterId,
+            title: "Linear Project: mock-project-id (Mock Team)",
+            children: ["issue-1", "issue-2"],
+        });
+    });
+    (0, vitest_1.it)("should throw an error if teamId is not found", async () => {
+        config.tracker.linear.teamId = "non-existent-team";
+        linearClient.listTeams.mockResolvedValueOnce([
+            { id: "another-team-id", name: "Another Team" },
+        ]);
+        const adapter = new index_js_1.LinearAdapter(config, linearClient);
+        await (0, vitest_1.expect)(adapter.syncIn()).rejects.toThrow("Linear team with ID or name 'non-existent-team' not found.");
+    });
+    (0, vitest_1.it)("should throw an error if projectId is not found in team", async () => {
+        config.tracker.linear.projectId = "non-existent-project";
+        linearClient.listProjects.mockResolvedValueOnce([
+            { id: "another-project-id", name: "Another Project" },
+        ]);
+        const adapter = new index_js_1.LinearAdapter(config, linearClient);
+        await (0, vitest_1.expect)(adapter.syncIn()).rejects.toThrow("Linear project with ID or name 'non-existent-project' not found in team 'Mock Team'.");
+    });
+    (0, vitest_1.it)("should warn and fetch all issues if no teamId is specified", async () => {
+        config.tracker.linear.teamId = undefined;
+        const consoleWarnSpy = vitest_1.vi.spyOn(console, 'warn').mockImplementation(() => { });
+        linearClient.listIssues.mockResolvedValueOnce([
+            {
+                id: "issue-3",
+                title: "Global Issue",
+                state: { id: "status-id-3", name: "Todo" },
+                relations: { nodes: [] },
+                inverseRelations: { nodes: [] },
+                children: { nodes: [] },
+            },
+        ]);
+        const adapter = new index_js_1.LinearAdapter(config, linearClient);
+        const graph = await adapter.syncIn();
+        const fullGraph = graph.fullGraph;
+        (0, vitest_1.expect)(consoleWarnSpy).toHaveBeenCalledWith("No Linear teamId specified in config. Fetching all accessible Linear issues. Consider specifying 'teamId' for better scope.");
+        (0, vitest_1.expect)(fullGraph.nodes["issue-3"]).toBeDefined();
+        (0, vitest_1.expect)(fullGraph.activeCluster).toBe("default");
+        (0, vitest_1.expect)(fullGraph.clusters["default"].title).toBe("All Linear Issues");
+        consoleWarnSpy.mockRestore();
+    });
+    (0, vitest_1.it)("syncs by Linear issue identifier including children and dependency relations", async () => {
+        const adapter = new index_js_1.LinearAdapter(config, linearClient);
+        const graph = await adapter.syncIn("POL-198");
+        const fullGraph = graph.fullGraph;
+        (0, vitest_1.expect)(linearClient.getIssueById).toHaveBeenCalledWith("POL-198");
+        (0, vitest_1.expect)(linearClient.getIssueById).toHaveBeenCalledWith("child-issue-id");
+        (0, vitest_1.expect)(fullGraph.activeCluster).toBe("POL-198");
+        (0, vitest_1.expect)(fullGraph.clusters["POL-198"].children.slice().sort()).toEqual(["POL-198", "POL-199", "POL-200", "POL-42"].sort());
+        (0, vitest_1.expect)(fullGraph.nodes["POL-198"]).toEqual({
+            id: "POL-198",
+            title: "Root issue",
+            status: "Todo",
+        });
+        (0, vitest_1.expect)(fullGraph.nodes["POL-200"]).toEqual({
+            id: "POL-200",
+            title: "Child issue",
+            status: "In Progress",
+        });
+        (0, vitest_1.expect)(fullGraph.dependencies["POL-198"]).toEqual(["POL-42"]);
+        (0, vitest_1.expect)(fullGraph.dependencies["POL-199"]).toEqual(["POL-198"]);
+    });
+    (0, vitest_1.it)("ignores unknown relation types safely", async () => {
+        const consoleWarnSpy = vitest_1.vi.spyOn(console, "warn").mockImplementation(() => { });
+        linearClient.listIssues.mockResolvedValueOnce([
+            {
+                id: "issue-unknown-rel",
+                title: "Issue with unknown relation",
+                state: { id: "status-id-1", name: "Todo" },
+                relations: {
+                    nodes: [
+                        {
+                            id: "rel-unknown",
+                            type: "related",
+                            issue: { id: "issue-unknown-rel" },
+                            relatedIssue: { id: "issue-other" },
+                        },
+                    ],
+                },
+                inverseRelations: { nodes: [] },
+                children: { nodes: [] },
+            },
+        ]);
+        const adapter = new index_js_1.LinearAdapter(config, linearClient);
+        const graph = await adapter.syncIn();
+        const fullGraph = graph.fullGraph;
+        (0, vitest_1.expect)(fullGraph.dependencies["issue-unknown-rel"]).toBeUndefined();
+        (0, vitest_1.expect)(consoleWarnSpy).toHaveBeenCalledWith("Linear relation type 'related' is not mapped to dependencies (supported types: blocks, blocked_by, depends_on); ignoring.");
+        consoleWarnSpy.mockRestore();
+    });
+});

package/dist/tracker/adapters/linear.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LinearAdapter = void 0;
+/**
+ * Placeholder Linear Adapter for demonstration and testing purposes.
+ * This adapter simulates interactions with Linear.
+ */
+class LinearAdapter {
+    /**
+     * Simulates fetching data from Linear.
+     * @param input - The sync input parameters.
+     * @returns A promise resolving to mock data.
+     */
+    async fetchData(input) {
+        console.log(`LinearAdapter: Simulating fetchData for trackerId: ${input.trackerId}`);
+        // Return some mock data for demonstration
+        return [
+            { id: 'LIN-1', title: 'Mock Issue 1', description: 'This is a mock issue.' },
+            { id: 'LIN-2', title: 'Mock Issue 2', description: 'Another mock issue.' },
+        ];
+    }
+    /**
+     * Simulates applying a mutation to Linear.
+     * @param mutation - The mutation record to apply.
+     * @returns A promise resolving to the updated mutation record.
+     */
+    async applyMutation(mutation) {
+        console.log(`LinearAdapter: Simulating applyMutation for mutation ID: ${mutation.id}`);
+        // Simulate success
+        return { ...mutation, status: 'succeeded', remoteId: `remote-${mutation.entityId}` };
+    }
+    /**
+     * Simulates conflict detection. Always returns false for now.
+     * @returns Always returns false.
+     */
+    detectConflict(localEntity, remoteEntity) {
+        console.log('LinearAdapter: Simulating conflict detection (always false)');
+        return false; // No conflicts for now
+    }
+    /**
+     * Simulates remote fingerprint generation.
+     * @param entity - The entity to generate a fingerprint for.
+     * @returns A simple mock fingerprint string.
+     */
+    generateRemoteFingerprint(entity) {
+        console.log('LinearAdapter: Simulating remote fingerprint generation');
+        return `mock-fingerprint-${entity.id || 'unknown'}`;
+    }
+}
+exports.LinearAdapter = LinearAdapter;

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

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalAdapter = void 0;
+const local_graph_js_1 = require("../../local-graph.js");
+class LocalAdapter {
+    async syncIn(clusterId, repoRoot = process.cwd()) {
+        return local_graph_js_1.LocalGraph.load(clusterId, repoRoot);
+    }
+}
+exports.LocalAdapter = LocalAdapter;

package/dist/tracker/adapters/local-file/index.js

@@ -0,0 +1,159 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalFileAdapter = void 0;
+/**
+ * Local-file tracker adapter for file-backed task management.
+ *
+ * This adapter provides a stable file-backed task model using the LocalGraph
+ * execution graph as its backing store. It supports read operations and
+ * limited mutation capabilities appropriate for local development workflows.
+ */
+class LocalFileAdapter {
+    /**
+     * Returns the capabilities supported by the local-file adapter.
+     */
+    getCapabilities() {
+        return {
+            supportsChildRelationships: true,
+            supportsStatusUpdates: true,
+            supportsComments: false, // Comments would require file format changes
+            supportsLinks: false, // Links would require file format changes
+            supportsDependencies: true,
+            supportsLifecycleMapping: true,
+            supportsCreateChild: true, // Via graph mutation
+        };
+    }
+    /**
+     * Maps a local-file status to a normalized lifecycle state.
+     *
+     * The local-file adapter uses the same normalized lifecycle states as
+     * Polaris config, so mapping is straightforward.
+     *
+     * @param nativeStatus - The native status string from the local graph.
+     * @returns A status mapping result with the normalized state and support status.
+     */
+    mapNativeStatus(nativeStatus) {
+        const normalizedStatus = nativeStatus.toLowerCase().trim();
+        // Local-file uses the same normalized lifecycle states
+        const validStates = [
+            "backlog",
+            "in_progress",
+            "in_review",
+            "done",
+            "blocked",
+            "cancelled",
+            "no_status_change",
+        ];
+        if (validStates.includes(normalizedStatus)) {
+            return {
+                lifecycleState: normalizedStatus,
+                supported: true,
+            };
+        }
+        return {
+            lifecycleState: "no_status_change",
+            supported: false,
+            reason: `Unknown local-file status '${nativeStatus}'. Valid states are: ${validStates.join(", ")}`,
+        };
+    }
+    /**
+     * Attempts to transition a local-file task to a lifecycle state.
+     *
+     * This would update the task's status in the LocalGraph. For now,
+     * this is a placeholder that returns skip results.
+     *
+     * @param taskId - The task ID in the local graph.
+     * @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",
+            };
+        }
+        // Placeholder implementation - would update LocalGraph node status
+        console.warn(`LocalFileAdapter: transitionLifecycleState not fully implemented. Would transition ${taskId} to ${lifecycleState}.`);
+        return {
+            applied: false,
+            skipped: true,
+            skipReason: "Lifecycle state transitions are not yet implemented for local-file adapter",
+        };
+    }
+    /**
+     * Adds a comment to a local-file task.
+     *
+     * Comments are not currently supported by the local-file format.
+     *
+     * @param taskId - The task ID in the local graph.
+     * @param body - The comment body text.
+     * @returns A comment result indicating success, skip, or failure.
+     */
+    async addComment(taskId, body) {
+        return {
+            added: false,
+            unsupported: true,
+            reason: "Local-file adapter does not support comments. The file format does not include comment storage.",
+        };
+    }
+    /**
+     * Attaches a link to a local-file task.
+     *
+     * Links are not currently supported by the local-file format.
+     *
+     * @param taskId - The task ID in the local graph.
+     * @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) {
+        return {
+            attached: false,
+            unsupported: true,
+            reason: "Local-file adapter does not support link attachments. The file format does not include link storage.",
+        };
+    }
+    /**
+     * Adds a dependency relation between local-file tasks.
+     *
+     * This would update the dependency map in the LocalGraph. For now,
+     * this is a placeholder that returns skip results.
+     *
+     * @param taskId - The ID of the task that depends on another.
+     * @param dependsOnTaskId - The ID of the task that is depended on.
+     * @returns A dependency result indicating success, skip, or failure.
+     */
+    async addDependency(taskId, dependsOnTaskId) {
+        // Placeholder implementation - would update LocalGraph dependency map
+        console.warn(`LocalFileAdapter: addDependency not fully implemented. Would add dependency from ${taskId} to ${dependsOnTaskId}.`);
+        return {
+            added: false,
+            unsupported: false,
+            error: "Adding dependencies is not yet implemented for local-file adapter",
+        };
+    }
+    /**
+     * Creates a child task under a parent task in the local graph.
+     *
+     * This would create a new node in the LocalGraph. For now,
+     * this is a placeholder that returns skip results.
+     *
+     * @param parentId - The ID of the parent task.
+     * @param title - The title of the child task.
+     * @param body - Optional body/description of the child task.
+     * @returns A create child result indicating success, skip, or failure.
+     */
+    async createChild(parentId, title, body) {
+        // Placeholder implementation - would create new node in LocalGraph
+        console.warn(`LocalFileAdapter: createChild not fully implemented. Would create child '${title}' under ${parentId}.`);
+        return {
+            created: false,
+            unsupported: false,
+            error: "Creating child tasks is not yet implemented for local-file adapter",
+        };
+    }
+}
+exports.LocalFileAdapter = LocalFileAdapter;

package/dist/tracker/adapters/mcp-bridge.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpBridgeAdapter = void 0;
+const MCP_BRIDGE_UNAVAILABLE_MESSAGE = "MCP bridge adapter is unavailable because '@tool-server/linear' is not installed. Install MCP bridge dependencies or switch tracker.adapter to 'linear'.";
+function isMissingModuleError(error) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    return (error.message.includes("Cannot find module '@tool-server/linear'") ||
+        error.message.includes("Cannot find package '@tool-server/linear'") ||
+        error.message.includes("ERR_MODULE_NOT_FOUND"));
+}
+async function loadMcpLinearTools() {
+    try {
+        const tools = await import("@tool-server/linear");
+        return {
+            mcp_linear_list_issues: tools.mcp_linear_list_issues,
+            mcp_linear_save_issue: tools.mcp_linear_save_issue,
+        };
+    }
+    catch (error) {
+        if (isMissingModuleError(error)) {
+            throw new Error(MCP_BRIDGE_UNAVAILABLE_MESSAGE);
+        }
+        throw error;
+    }
+}
+/**
+ * MCP Bridge Adapter for interacting with Linear via the MCP.
+ * This adapter fetches issues from Linear and applies mutations (e.g., status updates) to Linear issues.
+ */
+class McpBridgeAdapter {
+    toolsLoader;
+    toolsPromise;
+    constructor(toolsLoader = loadMcpLinearTools) {
+        this.toolsLoader = toolsLoader;
+    }
+    async getTools() {
+        this.toolsPromise ??= this.toolsLoader().catch((error) => {
+            this.toolsPromise = undefined;
+            if (isMissingModuleError(error)) {
+                throw new Error(MCP_BRIDGE_UNAVAILABLE_MESSAGE);
+            }
+            throw error;
+        });
+        return this.toolsPromise;
+    }
+    /**
+     * Fetches data (issues) from Linear using the MCP bridge.
+     * @param input - The sync input parameters, including the Linear team ID.
+     * @returns A promise resolving to an array of Linear issues.
+     */
+    async fetchData(input) {
+        const { mcp_linear_list_issues } = await this.getTools();
+        console.log(`McpBridgeAdapter: Fetching data for trackerId: ${input.trackerId}`);
+        // Assuming input.trackerId contains the Linear team ID or can be derived from config
+        // For now, let's assume we need a team ID to list issues. This will need to come from configuration.
+        // As a placeholder, we'll use a hardcoded team if not provided in input.
+        const teamId = input.trackerId; // This needs to be refined based on actual config
+        if (!teamId) {
+            console.warn('McpBridgeAdapter: No teamId provided in TrackerSyncInput. Cannot fetch issues.');
+            return [];
+        }
+        try {
+            const issues = await mcp_linear_list_issues({ team: teamId });
+            console.log(`McpBridgeAdapter: Fetched ${issues.length} issues from Linear.`);
+            return issues;
+        }
+        catch (error) {
+            console.error('McpBridgeAdapter: Error fetching issues from Linear:', error);
+            throw error;
+        }
+    }
+    /**
+     * Applies a mutation record to a Linear issue using the MCP bridge.
+     * @param mutation - The mutation record to apply.
+     * @returns A promise resolving to the updated mutation record.
+     */
+    async applyMutation(mutation) {
+        const { mcp_linear_save_issue } = await this.getTools();
+        console.log(`McpBridgeAdapter: Applying mutation for ID: ${mutation.id}, entityType: ${mutation.entityType}, entityId: ${mutation.entityId}`);
+        if (mutation.entityType === 'issue' && mutation.type === 'update') {
+            try {
+                // Assuming payload contains fields to update in Linear issue
+                const updatedIssue = await mcp_linear_save_issue({
+                    id: mutation.entityId,
+                    ...mutation.payload, // Spread the payload to update issue fields
+                });
+                console.log(`McpBridgeAdapter: Successfully updated Linear issue ${mutation.entityId}.`);
+                return { ...mutation, status: 'succeeded', remoteId: updatedIssue.id };
+            }
+            catch (error) {
+                console.error(`McpBridgeAdapter: Error updating Linear issue ${mutation.entityId}:`, error);
+                return { ...mutation, status: 'failed', error: error.message };
+            }
+        }
+        else if (mutation.entityType === 'issue' && mutation.type === 'create') {
+            try {
+                // Assuming payload contains fields to create a Linear issue
+                if (!mutation.payload.team) {
+                    return { ...mutation, status: 'failed', error: 'Team is required for creating a Linear issue.' };
+                }
+                if (!mutation.payload.title) {
+                    return { ...mutation, status: 'failed', error: 'Title is required for creating a Linear issue.' };
+                }
+                const newIssue = await mcp_linear_save_issue({
+                    team: mutation.payload.team,
+                    title: mutation.payload.title,
+                    description: mutation.payload.description,
+                    // Add other fields as necessary from payload
+                    ...mutation.payload,
+                });
+                console.log(`McpBridgeAdapter: Successfully created Linear issue ${newIssue.id}.`);
+                return { ...mutation, status: 'succeeded', remoteId: newIssue.id };
+            }
+            catch (error) {
+                console.error(`McpBridgeAdapter: Error creating Linear issue:`, error);
+                return { ...mutation, status: 'failed', error: error.message };
+            }
+        }
+        // Handle other mutation types or entity types as needed
+        console.warn(`McpBridgeAdapter: Unsupported mutation type or entity type: ${mutation.type} ${mutation.entityType}`);
+        return { ...mutation, status: 'failed', error: 'Unsupported mutation type or entity type' };
+    }
+    /**
+     * Compares local state with remote state to detect conflicts.
+     * This is a placeholder and needs a proper implementation based on how local and remote entities are structured.
+     * A common approach is to compare a "version" field or a hash of relevant fields.
+     * @param localEntity - The local representation of an entity.
+     * @param remoteEntity - The remote representation of the same entity.
+     * @returns True if a conflict is detected, false otherwise.
+     */
+    detectConflict(localEntity, remoteEntity) {
+        // For a basic implementation, we can compare a lastUpdated timestamp or a content hash.
+        // This will depend on the structure of localEntity and LinearIssue.
+        // For now, a very basic comparison:
+        if (!localEntity || !remoteEntity) {
+            return false; // Cannot detect conflict if one is missing
+        }
+        // More sophisticated conflict detection would compare relevant fields, e.g.,
+        // if (localEntity.lastUpdated > remoteEntity.updatedAt) { return true; }
+        // Or if (JSON.stringify(localEntity.importantFields) !== JSON.stringify(remoteEntity.importantFields)) { return true; }
+        console.log('McpBridgeAdapter: Simulating conflict detection (always false for now)');
+        return false; // Placeholder
+    }
+    /**
+     * Generates a remote fingerprint for a given Linear entity (issue).
+     * This fingerprint can be used for quick comparison to detect changes.
+     * @param entity - The entity to generate a fingerprint for.
+     * @returns A string representing the remote fingerprint.
+     */
+    generateRemoteFingerprint(entity) {
+        // A simple fingerprint could be a hash of the issue's content and its last update timestamp.
+        // For Linear issues, `updatedAt` is a good candidate.
+        return `${entity.id}-${entity.updatedAt}-${entity.title}-${entity.description}`; // Basic fingerprint
+    }
+}
+exports.McpBridgeAdapter = McpBridgeAdapter;

package/dist/tracker/adapters/mcp-bridge.test.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const mcp_bridge_js_1 = require("./mcp-bridge.js");
+(0, vitest_1.describe)("McpBridgeAdapter", () => {
+    (0, vitest_1.it)("fails gracefully when MCP bridge dependencies are missing", async () => {
+        const adapter = new mcp_bridge_js_1.McpBridgeAdapter(async () => {
+            throw new Error("Cannot find module '@tool-server/linear'");
+        });
+        await (0, vitest_1.expect)(adapter.fetchData({ trackerId: "POL-1" })).rejects.toThrow("MCP bridge adapter is unavailable because '@tool-server/linear' is not installed.");
+    });
+});